@workclaw/openclaw-workchat 1.0.4 → 1.1.0

package/index.ts

@@ -3,6 +3,7 @@ import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-sch
 
 import { workchatPlugin } from "./src/channel.js";
 import { assertHostCompatibility } from "./src/compat.js";
+import { migrateLegacyDefaultWorkChatAccount } from "./src/auth/accounts.js";
 import { WorkChatConfigSchema } from "./src/config/config-schema.js";
 
 export default {
@@ -14,6 +15,12 @@ export default {
     // Fail-fast: reject incompatible host versions before any side-effects.
     assertHostCompatibility(api.runtime?.version);
 
+    // Rename legacy `default` accounts to the agent-scoped key before the
+    // channel starts enumerating accounts (one-way, idempotent).
+    void migrateLegacyDefaultWorkChatAccount().catch(err => {
+      console.error("[openclaw-workchat] legacy default account migration failed:", err);
+    });
+
     api.registerChannel({ plugin: workchatPlugin });
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workclaw/openclaw-workchat",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "type": "module",
   "description": "OpenClaw WorkChat channel plugin: QR binding + WebSocket messaging with the WorkChat open platform",
   "license": "MIT",

package/src/api/api.ts

@@ -1,5 +1,3 @@
-import { Agent, fetch as undiciFetch } from "undici";
-
 import { DEFAULT_BASE_URL, DEFAULT_WS_URL, RequestDefaults } from "./types.js";
 import { logger } from "../util/logger.js";
 import { redactBody, redactUrl } from "../util/redact.js";
@@ -23,10 +21,13 @@ async function fetchJson<T>(params: {
   allowInsecureTls?: boolean;
 }): Promise<T> {
   const { url, init, timeoutMs, allowInsecureTls } = params;
-  const dispatcher = allowInsecureTls
-    ? new Agent({ connect: { rejectUnauthorized: false } })
-    : undefined;
-  const fetcher = allowInsecureTls ? undiciFetch : globalThis.fetch;
+  void allowInsecureTls; // TLS verification always on (see fetcher note below)
+  // Native fetch only: undici's fetch serializes FormData file parts without
+  // the Blob's Content-Type (backend rejects with 4006 "不支持的媒体类型"),
+  // while Node's built-in fetch preserves it. allowInsecureTls is not used by
+  // any WorkChat deployment (workbrain.cn is public TLS), so dropping the
+  // undici path here is safe and keeps multipart uploads working.
+  const fetcher = globalThis.fetch;
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
 
@@ -36,7 +37,6 @@ async function fetchJson<T>(params: {
     response = await fetcher(url, {
       ...init,
       signal: controller.signal,
-      ...(dispatcher ? { dispatcher } : {}),
     } as any);
     text = await response.text().catch(() => "");
   } finally {
@@ -239,6 +239,73 @@ export async function sendWorkChatReplyMessage(params: {
   return { msgId: String(data.msgId) };
 }
 
+// ---------------------------------------------------------------------------
+// File upload (media send pipeline)
+// ---------------------------------------------------------------------------
+
+/** Response of POST /open-apis/v1/files/upload (backend FileUploadResp). */
+export interface WorkChatFileUploadResult {
+  url: string;
+  fileName?: string;
+  suffix?: string;
+  fileSize?: number;
+}
+
+/**
+ * POST {base}/open-apis/v1/files/upload — multipart single-file upload.
+ * Goes to the public bucket (SYSTEM_RESOURCE), so the returned URL is
+ * permanent and safe to embed in image/audio message content.
+ * Field name must be `file` (backend UploadFileReq).
+ */
+export async function uploadWorkChatFile(params: {
+  opts: WorkChatApiOptions;
+  filePath: string;
+  /** WorkChat user id — required by the backend as the login user (form field + x-user-id header). */
+  userId?: string | number;
+}): Promise<WorkChatFileUploadResult> {
+  const { opts, filePath, userId } = params;
+  const token = await getAccessToken(opts);
+  const { readFile } = await import("node:fs/promises");
+  const pathMod = await import("node:path");
+  const content = await readFile(filePath);
+  const fileName = pathMod.basename(filePath);
+  // The backend rejects non image/* or audio/* part content-types (4006), so
+  // the MIME must reflect the actual file — the send pipeline routes by
+  // extension already (audio: wav/m4a/mp3, else image).
+  const ext = pathMod.extname(fileName).replace(/^\./, "").toLowerCase();
+  const mime = ext === "mp3" || ext === "m4a" ? "audio/mpeg" : ext === "wav" ? "audio/wav" : `image/${ext === "jpg" ? "jpeg" : ext || "png"}`;
+  const form = new FormData();
+  form.set("file", new Blob([new Uint8Array(content)], { type: mime }), fileName);
+  // Backend UploadFileReq.userId: the file owner. The gateway normally injects
+  // x-user-id for user tokens; the plugin's app token does not carry it, so
+  // both the form field and the header are sent explicitly.
+  const ownerUserId = userId !== undefined && String(userId).trim() !== "" ? String(userId) : "0";
+  form.set("userId", ownerUserId);
+
+  const resp = await fetchJson<{ code?: number; message?: string; data?: { url?: string; fileName?: string; suffix?: string; fileSize?: number } }>({
+    url: `${normalizeBaseUrl(opts.baseUrl)}/open-apis/v1/files/upload`,
+    timeoutMs: opts.timeoutMs ?? RequestDefaults.TimeoutMs,
+    allowInsecureTls: opts.allowInsecureTls,
+    init: {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "x-user-id": ownerUserId,
+      },
+      body: form,
+    },
+  });
+  const data = unwrapEnvelope(resp);
+  const url = typeof data?.url === "string" ? data.url.trim() : "";
+  if (!url) throw new Error("workchat: url missing in file upload response");
+  return {
+    url,
+    fileName: typeof data?.fileName === "string" ? data.fileName : undefined,
+    suffix: typeof data?.suffix === "string" ? data.suffix : undefined,
+    fileSize: typeof data?.fileSize === "number" ? data.fileSize : undefined,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Agent lifecycle
 // ---------------------------------------------------------------------------

package/src/api/session-guard.ts

@@ -0,0 +1,84 @@
+import { logger } from "../util/logger.js";
+
+const SESSION_PAUSE_DURATION_MS = 60 * 60 * 1000;
+
+/**
+ * Backend error strings that indicate a permanent binding failure (agent
+ * deleted / not owned by this appKey). Retrying within the session cannot
+ * fix these — only a re-scan (new binding QR) can.
+ */
+const PERMANENT_ERROR_PATTERNS = [
+  "智能体不能为空",
+  "智能体不是接收人的智能体",
+  "设备链接异常",
+  "申请绑定的AppKey不存在",
+];
+
+const pauseUntilMap = new Map<string, number>();
+
+/** Pause all send attempts for `accountId` for one hour (permanent backend error). */
+export function pauseSession(accountId: string): void {
+  const until = Date.now() + SESSION_PAUSE_DURATION_MS;
+  pauseUntilMap.set(accountId, until);
+  logger.info(
+    `session-guard: paused accountId=${accountId} until=${new Date(until).toISOString()} (${SESSION_PAUSE_DURATION_MS / 1000}s)`,
+  );
+}
+
+/** Returns `true` when the account is still within its one-hour cooldown window. */
+export function isSessionPaused(accountId: string): boolean {
+  const until = pauseUntilMap.get(accountId);
+  if (until === undefined) return false;
+  if (Date.now() >= until) {
+    pauseUntilMap.delete(accountId);
+    return false;
+  }
+  return true;
+}
+
+/** Milliseconds remaining until the pause expires (0 when not paused). */
+export function getRemainingPauseMs(accountId: string): number {
+  const until = pauseUntilMap.get(accountId);
+  if (until === undefined) return 0;
+  const remaining = until - Date.now();
+  if (remaining <= 0) {
+    pauseUntilMap.delete(accountId);
+    return 0;
+  }
+  return remaining;
+}
+
+/** Throw if the session is currently paused. Call before any send request. */
+export function assertSessionActive(accountId: string): void {
+  if (isSessionPaused(accountId)) {
+    const remainingMin = Math.ceil(getRemainingPauseMs(accountId) / 60_000);
+    throw new Error(
+      `session paused for accountId=${accountId}, ${remainingMin} min remaining — the WorkChat binding is invalid, re-scan the QR code to fix`,
+    );
+  }
+}
+
+/** True when a backend error message indicates a permanent binding failure. */
+export function isPermanentBindingError(errMsg: string): boolean {
+  return PERMANENT_ERROR_PATTERNS.some((p) => errMsg.includes(p));
+}
+
+/**
+ * Auto-pause the account when the error looks like a permanent binding
+ * failure. Returns true when the pause was armed.
+ */
+export function pauseOnPermanentError(accountId: string, errMsg: string): boolean {
+  if (!isPermanentBindingError(errMsg)) return false;
+  if (!isSessionPaused(accountId)) {
+    pauseSession(accountId);
+    logger.warn(
+      `session-guard: permanent binding error, pausing accountId=${accountId} err="${errMsg.slice(0, 120)}" — re-scan required`,
+    );
+  }
+  return true;
+}
+
+/** Reset internal state — only for tests. @internal */
+export function _resetSessionGuardForTest(): void {
+  pauseUntilMap.clear();
+}

package/src/api/types.ts

@@ -13,10 +13,19 @@ export const DEFAULT_BASE_URL = "https://workbrain.cn/backend-api";
 /** WebSocket endpoint used when the open-connection API returns none. */
 export const DEFAULT_WS_URL = "wss://workbrain.cn/backend-api/open-apis/connect";
 
-/** msgType codes accepted by /open-apis/im/v1/messages. */
+/**
+ * msgType values accepted by /open-apis/im/v1/messages — the backend ChatType
+ * enum deserializes by NUMERIC CODE (verified live: name strings like "text"
+ * fail with 2001 请求体格式错误, while codes "1"/1/2/"2" pass through to the
+ * business layer). Codes from the backend ChatType enum: TEXT=1, IMAGE=2,
+ * Voice=110. Audio rides Voice(110) — the integration guide's "audio" name
+ * does not match the live deserializer.
+ * Media content is a JSON string: image {"url", width?, height?}, audio {"url", duration?}.
+ */
 export const WorkChatMsgType = {
   Text: "1",
-  Rich: "26",
+  Image: "2",
+  Audio: "110",
 } as const;
 
 export const RequestDefaults = {
@@ -39,7 +48,13 @@ export interface AgentMessagePayload {
   agentId?: string | number;
   conversationId?: string;
   msgId?: string | number;
-  message?: string | { content?: string };
+  message?: string | { content?: string; type?: string };
+  /** Backend ChatAgentMessageDTO: chatType mirrors message.type for media. */
+  chatType?: string | number;
+  /** Single file id (backend DTO fileId). */
+  fileId?: string | number;
+  /** File url list (backend DTO fileUrl) — populated for file/image/audio messages. */
+  fileUrl?: string[];
 }
 
 /** EVENT/AGENT_CREATED|INIT_AGENT payload. */

package/src/auth/accounts.ts

@@ -21,6 +21,10 @@ function resolveAccountIndexPath(): string {
 
 /** Returns all accountIds registered via binding QR. */
 export function listIndexedWorkChatAccountIds(): string[] {
+  return readAccountIndex();
+}
+
+function readAccountIndex(): string[] {
   const filePath = resolveAccountIndexPath();
   try {
     if (!fs.existsSync(filePath)) return [];
@@ -32,22 +36,43 @@ export function listIndexedWorkChatAccountIds(): string[] {
   }
 }
 
+/**
+ * Serialize index mutations inside the plugin process. All writers (binding
+ * registration, rebind pruning, legacy migration) run in this one process;
+ * the shared promise chain guarantees read-modify-write never interleaves.
+ */
+let indexUpdateChain: Promise<void> = Promise.resolve();
+
+/**
+ * Read-modify-write the account index. Mutations are serialized in-process
+ * (see indexUpdateChain); the framework file lock is not used because the
+ * index is only ever written by this plugin process, and the lock sidecar
+ * behaves inconsistently under test-runner module isolation.
+ */
+async function updateAccountIndex(
+  mutator: (ids: string[]) => string[],
+): Promise<void> {
+  const run = indexUpdateChain.then(() => {
+    const filePath = resolveAccountIndexPath();
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const updated = mutator(readAccountIndex());
+    fs.writeFileSync(filePath, JSON.stringify(updated, null, 2), "utf-8");
+  });
+  // Keep the chain alive even when a mutation fails.
+  indexUpdateChain = run.then(() => undefined, () => undefined);
+  await run;
+}
+
 /** Add accountId to the persistent index (no-op if already present). */
-export function registerWorkChatAccountId(accountId: string): void {
-  const dir = resolveWorkChatStateDir();
-  fs.mkdirSync(dir, { recursive: true });
-  const existing = listIndexedWorkChatAccountIds();
-  if (existing.includes(accountId)) return;
-  fs.writeFileSync(resolveAccountIndexPath(), JSON.stringify([...existing, accountId], null, 2), "utf-8");
+export async function registerWorkChatAccountId(accountId: string): Promise<void> {
+  await updateAccountIndex(ids =>
+    ids.includes(accountId) ? ids : [...ids, accountId],
+  );
 }
 
 /** Remove accountId from the persistent index. */
-export function unregisterWorkChatAccountId(accountId: string): void {
-  const existing = listIndexedWorkChatAccountIds();
-  const updated = existing.filter(id => id !== accountId);
-  if (updated.length !== existing.length) {
-    fs.writeFileSync(resolveAccountIndexPath(), JSON.stringify(updated, null, 2), "utf-8");
-  }
+export async function unregisterWorkChatAccountId(accountId: string): Promise<void> {
+  await updateAccountIndex(ids => ids.filter(id => id !== accountId));
 }
 
 // ---------------------------------------------------------------------------
@@ -115,14 +140,14 @@ export function saveWorkChatAccount(
 }
 
 /** Remove all files associated with an account. */
-export function clearWorkChatAccount(accountId: string): void {
+export async function clearWorkChatAccount(accountId: string): Promise<void> {
   const filePath = resolveAccountPath(accountId);
   try {
     if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
   } catch (err) {
     logger.warn(`clearWorkChatAccount: failed to remove ${filePath}: ${String(err)}`);
   }
-  unregisterWorkChatAccountId(accountId);
+  await unregisterWorkChatAccountId(accountId);
 }
 
 /**
@@ -152,23 +177,22 @@ export async function removeWorkChatAccountBinding(accountId: string): Promise<v
 }
 
 /**
- * Remove every registered account whose stored agentId differs from
- * `keepAgentId` (rebind cleanup). Returns the removed accountIds.
- * `default` is normalized: if it holds a foreign agentId it is removed too;
- * the surviving binding keeps whatever account key it was registered under.
+ * Remove every registered account other than `keepAccountId` (rebind cleanup).
+ * One active agent per host: a completed binding owns the agent-scoped key
+ * `agent-${agentId}`, and every other account — a previous agent, or a legacy
+ * `default` registered by older plugin versions even for the SAME agent — is
+ * removed so a re-scan can never leave duplicate accounts behind.
  */
-export async function pruneStaleWorkChatAccounts(keepAgentId: string): Promise<string[]> {
+export async function pruneOtherWorkChatAccounts(keepAccountId: string): Promise<string[]> {
+  const keep = keepAccountId.trim();
   const removed: string[] = [];
   for (const accountId of listIndexedWorkChatAccountIds()) {
-    const data = loadWorkChatAccount(accountId);
-    const storedAgentId = data?.agentId?.trim();
-    if (storedAgentId && storedAgentId !== keepAgentId) {
-      await removeWorkChatAccountBinding(accountId);
-      removed.push(accountId);
-      logger.info(
-        `pruneStaleWorkChatAccounts: removed account=${accountId} agent=${storedAgentId} (superseded by agent=${keepAgentId})`,
-      );
-    }
+    if (accountId === keep) continue;
+    await removeWorkChatAccountBinding(accountId);
+    removed.push(accountId);
+    logger.info(
+      `pruneOtherWorkChatAccounts: removed account=${accountId} (superseded by ${keep})`,
+    );
   }
   return removed;
 }
@@ -211,6 +235,62 @@ type WorkChatSectionConfig = WorkChatAccountConfig & {
   channelConfigUpdatedAt?: string;
 };
 
+/**
+ * One-time migration for accounts registered by older plugin versions under
+ * the `default` key: rename them to the agent-scoped key `agent-${agentId}`.
+ * Moves the account data file and the framework allowFrom credentials so no
+ * orphaned files remain (the gateway startup migration treats orphaned
+ * allowFrom files as a fatal unresolved state). Idempotent — a no-op once no
+ * `default` account exists. Runs once at plugin registration (see index.ts),
+ * before any binding listener can start, so it cannot interleave with
+ * concurrent binding writes (register/unregister hold the index file lock).
+ */
+export async function migrateLegacyDefaultWorkChatAccount(): Promise<boolean> {
+  const ids = listIndexedWorkChatAccountIds();
+  if (!ids.includes("default")) return false;
+  const data = loadWorkChatAccount("default");
+  const agentId = data?.agentId?.trim();
+  if (!agentId) return false;
+  const targetId = `agent-${agentId}`;
+
+  // 1. Persist the agent-scoped copy (unless it already exists — the
+  //    agent-scoped file is the newer binding when both are present).
+  if (!ids.includes(targetId)) {
+    saveWorkChatAccount(targetId, { ...data });
+  }
+  // 2. Move the framework allowFrom credentials to the new key.
+  try {
+    const { readFrameworkAllowFromList, registerUserInFrameworkStore } = await import("./pairing.js");
+    for (const userId of readFrameworkAllowFromList("default")) {
+      await registerUserInFrameworkStore({ accountId: targetId, userId });
+    }
+  } catch (err) {
+    logger.warn(`migrateLegacyDefaultWorkChatAccount: allowFrom move failed: ${String(err)}`);
+  }
+  // 3. Register the new key and drop the legacy one, both under the index
+  //    file lock so a concurrent binding cannot be lost.
+  await updateAccountIndex(existing => {
+    const next = existing.filter(id => id !== "default" && id !== targetId);
+    next.push(targetId);
+    return next;
+  });
+  try {
+    fs.rmSync(path.join(resolveWorkChatStateDir(), "accounts", "default.json"), { force: true });
+  } catch {
+    // Best-effort data file cleanup; the index above is authoritative.
+  }
+  try {
+    const { clearFrameworkAllowFromList } = await import("./pairing.js");
+    clearFrameworkAllowFromList("default");
+  } catch (err) {
+    logger.warn(`migrateLegacyDefaultWorkChatAccount: allowFrom cleanup failed: ${String(err)}`);
+  }
+  logger.info(
+    `migrateLegacyDefaultWorkChatAccount: renamed default -> ${targetId} (agent=${agentId})`,
+  );
+  return true;
+}
+
 /** List accountIds from the index file (written at binding). */
 export function listWorkChatAccountIds(_cfg: OpenClawConfig): string[] {
   return listIndexedWorkChatAccountIds();

package/src/auth/login-qr.ts

@@ -293,7 +293,6 @@ import { buildPongFrame } from "../messaging/inbound.js";
 import {
   saveWorkChatAccount,
   registerWorkChatAccountId,
-  listIndexedWorkChatAccountIds,
 } from "./accounts.js";
 
 const bindingListeners = new Map<string, { ws: WebSocket; done: boolean }>();
@@ -388,45 +387,39 @@ async function handleListenerFrame(sessionKey: string, data: string, ws: WebSock
 
   const eventData = result.eventData;
   if (!eventData) return;
-  const agentId = String(eventData.id ?? eventData.agentId ?? "");
+  const agentId = String(eventData.id ?? eventData.agentId ?? "").trim();
   if (!agentId) return;
-  const userId = String(eventData.futureId ?? eventData.userId ?? "");
+  const userId = String(eventData.futureId ?? eventData.userId ?? "").trim();
 
   const entry = bindingListeners.get(sessionKey);
   if (entry) entry.done = true;
 
-  // Rebind detection must happen BEFORE pruning empties the index: if any
-  // account existed, this scan replaces it. The QR login flow force-stops the
-  // channel (marked manually-stopped in the gateway), and a reused account id
-  // would stay stopped after reload — so a rebind always registers under a
-  // FRESH agent-scoped key instead of reusing `default`.
-  const isRebind = listIndexedWorkChatAccountIds().length > 0;
+  // One active agent per host (mirrors handleAgentLifecycleEvent): every
+  // binding registers under the agent-scoped key `agent-${agentId}`. The QR
+  // login flow force-stops the channel (marked manually-stopped in the
+  // gateway), and a reused account id would stay stopped after reload — the
+  // fresh agent-scoped key plus the channel reload restarts it.
+  const accountId = `agent-${agentId}`;
 
-  // Rebind semantics (mirrors handleAgentLifecycleEvent): a re-scan replaces
-  // the previously bound agent, so drop accounts bound to other agentIds
-  // before registering this one.
+  // A re-scan replaces the previously bound agent: drop every OTHER
+  // registered account (including a same-agent legacy `default`) before
+  // registering this one.
   try {
-    const { pruneStaleWorkChatAccounts } = await import("./accounts.js");
-    const removed = await pruneStaleWorkChatAccounts(agentId);
+    const { pruneOtherWorkChatAccounts } = await import("./accounts.js");
+    const removed = await pruneOtherWorkChatAccounts(accountId);
     if (removed.length > 0) {
-      logger.info(`binding listener: pruned stale account(s): ${removed.join(", ")}`);
+      logger.info(`binding listener: pruned previous account(s): ${removed.join(", ")}`);
     }
   } catch (err) {
     logger.error(`binding listener: rebind cleanup failed: ${String(err)}`);
   }
 
-  // First bound agent becomes the `default` account; a rebind gets a fresh
-  // agent-scoped key (see isRebind note above).
-  const accountId = isRebind
-    ? `agent-${agentId}`
-    : "default";
-
   try {
     saveWorkChatAccount(accountId, {
       agentId,
       ...(userId ? { userId } : {}),
     });
-    registerWorkChatAccountId(accountId);
+    await registerWorkChatAccountId(accountId);
     // Complete the binding: account data is already in the private state
     // dir; this call registers the allowFrom user and triggers the channel
     // hot reload.

package/src/channel.ts

@@ -5,12 +5,19 @@ import {
   listWorkChatAccountIds,
   resolveWorkChatAccount,
 } from "./auth/accounts.js";
+import { DEFAULT_BASE_URL } from "./api/types.js";
 import {
   startWorkChatLoginWithQr,
   waitForWorkChatLogin,
 } from "./auth/login-qr.js";
 import type { WorkChatQrStartResult, WorkChatQrWaitResult } from "./auth/login-qr.js";
 import { pushWorkChatMessage, replyWorkChatMessage } from "./messaging/send.js";
+import {
+  downloadRemoteMediaToTemp,
+  isLocalMediaSource,
+  resolveLocalMediaPath,
+  sendWorkChatMediaFile,
+} from "./messaging/send-media.js";
 import { logger } from "./util/logger.js";
 
 /**
@@ -70,7 +77,8 @@ export const workchatPlugin: ChannelPlugin<ResolvedWorkChatAccount> = {
     messageToolHints: () => [
       "To send a message to the current WorkChat user, use the message tool with action='send'. You do not need to specify 'to' — the current conversation recipient is used automatically.",
       "IMPORTANT: When creating a cron job (scheduled task) for the current WorkChat user, you MUST set delivery.to to the user's WorkChat ID (the numeric ID from the current conversation) AND set delivery.accountId to the current AccountId. Without an explicit 'to', the cron delivery will fail with 'requires target'. Without an explicit 'accountId', the message may be sent from the wrong bot account. Example: delivery: { mode: 'announce', channel: 'openclaw-workchat', to: '<current_user_id>', accountId: '<current_AccountId>' }.",
-      "IMPORTANT: When sending media, set 'media' to a URL the WorkChat platform can fetch (an HTTPS URL). Local file paths are not supported by the WorkChat send API yet — include the link in the message text instead.",
+      "To send an image or audio file to the current user, use the message tool with action='send' and set 'media' to a local file path or a remote HTTPS URL. Supported audio formats: wav, m4a, mp3; supported image formats: bmp, gif, jpg, jpeg, png, webp. Remote URLs are downloaded and re-uploaded to WorkChat storage automatically — the client renders image/audio cards, never bare links.",
+      "IMPORTANT: When generating or saving a file to send, always use an absolute path (e.g. /tmp/photo.png or C:\\tmp\\photo.png on Windows), never a relative path like ./photo.png. Relative paths cannot be resolved and the file will not be delivered.",
     ],
   },
   reload: { configPrefixes: ["channels.openclaw-workchat"] },
@@ -106,16 +114,73 @@ export const workchatPlugin: ChannelPlugin<ResolvedWorkChatAccount> = {
       return { channel: "openclaw-workchat", messageId: result.messageId };
     },
     sendMedia: async (ctx) => {
-      // Media sends degrade to a text message carrying the media URL until the
-      // platform media-upload API is confirmed.
       const account = resolveOutboundAccount(ctx.cfg, ctx.accountId);
-      const text = ctx.text?.trim() ? ctx.text : ctx.mediaUrl ?? "";
-      const result = await pushWorkChatMessage({
-        account,
+      const aLog = logger.withAccount(account.accountId);
+      const mediaUrl = ctx.mediaUrl?.trim();
+      let text = ctx.text ?? "";
+
+      // message_sending hook (mirrors the deliver path; weixin parity): lets
+      // hosts observe/cancel outbound media too.
+      const { applyWorkChatMessageSendingHook, emitWorkChatMessageSent } =
+        await import("./messaging/outbound-hooks.js");
+      const sendingResult = await applyWorkChatMessageSendingHook({
         to: ctx.to,
         text,
+        accountId: account.accountId,
+        mediaUrl,
+      }).catch((err: unknown) => {
+        aLog.warn(`message_sending hook error, proceeding: ${String(err)}`);
+        return { cancelled: false, text };
       });
-      return { channel: "openclaw-workchat", messageId: result.messageId };
+      if (sendingResult.cancelled) {
+        aLog.info(`sendMedia: cancelled by message_sending hook to=${ctx.to}`);
+        return { channel: "openclaw-workchat", messageId: "" };
+      }
+      text = sendingResult.text;
+
+      if (!mediaUrl) {
+        // No media: degrade to a plain text send.
+        try {
+          const result = await pushWorkChatMessage({ account, to: ctx.to, text });
+          emitWorkChatMessageSent({ to: ctx.to, content: text, success: true, accountId: account.accountId });
+          return { channel: "openclaw-workchat", messageId: result.messageId };
+        } catch (err) {
+          emitWorkChatMessageSent({ to: ctx.to, content: text, success: false, error: String(err), accountId: account.accountId });
+          throw err;
+        }
+      }
+
+      // Local file → upload directly; remote URL → relay through local temp
+      // (the WorkChat client renders only WorkChat-hosted image/audio cards).
+      let filePath: string;
+      try {
+        if (isLocalMediaSource(mediaUrl)) {
+          filePath = resolveLocalMediaPath(mediaUrl);
+          aLog.debug(`sendMedia: uploading local file ${filePath}`);
+        } else {
+          aLog.debug(`sendMedia: downloading remote mediaUrl=${mediaUrl.slice(0, 80)}...`);
+          filePath = await downloadRemoteMediaToTemp(mediaUrl);
+          aLog.debug(`sendMedia: remote media downloaded to ${filePath}`);
+        }
+      } catch (err) {
+        emitWorkChatMessageSent({ to: ctx.to, content: text, success: false, error: String(err), accountId: account.accountId });
+        throw err;
+      }
+
+      try {
+        const result = await sendWorkChatMediaFile({
+          account,
+          to: ctx.to,
+          filePath,
+          text,
+          replyToMessageId: ctx.replyToId?.trim() || undefined,
+        });
+        emitWorkChatMessageSent({ to: ctx.to, content: text, success: true, accountId: account.accountId });
+        return { channel: "openclaw-workchat", messageId: result.messageId };
+      } catch (err) {
+        emitWorkChatMessageSent({ to: ctx.to, content: text, success: false, error: String(err), accountId: account.accountId });
+        throw err;
+      }
     },
   },
   status: {
@@ -205,13 +270,24 @@ export const workchatPlugin: ChannelPlugin<ResolvedWorkChatAccount> = {
       // The gateway adapter has no cfg in scope here — read the live config
       // from disk (the gateway's own config, same file triggerWorkChatChannelReload
       // writes to) so the ${WORKCHAT_API_KEY} placeholder is resolved by the host.
+      // Account ids are always agent-scoped (`agent-${agentId}`); an explicit
+      // accountId targets that account, otherwise fall back to the first
+      // registered one. A first-time bind (empty index) still resolves an
+      // account-like view of the shared channel credentials — the QR flow
+      // only consumes baseUrl/appKey/appSecret.
       const { loadConfig } = await import("openclaw/plugin-sdk/config-runtime");
       const cfg = loadConfig() as OpenClawConfig;
-      const account = resolveWorkChatAccount(cfg, accountId ?? "default");
+      const requestedAccountId = accountId?.trim() || listWorkChatAccountIds(cfg)[0];
+      const existing = requestedAccountId
+        ? resolveWorkChatAccount(cfg, requestedAccountId)
+        : undefined;
+      const section = cfg.channels?.["openclaw-workchat"] as
+        | { baseUrl?: string; appKey?: string; appSecret?: string }
+        | undefined;
       const result: WorkChatQrStartResult = await startWorkChatLoginWithQr({
-        baseUrl: account.baseUrl,
-        appKey: account.appKey,
-        appSecret: account.appSecret,
+        baseUrl: existing?.baseUrl || section?.baseUrl || DEFAULT_BASE_URL,
+        appKey: existing?.appKey || section?.appKey?.trim() || undefined,
+        appSecret: existing?.appSecret || section?.appSecret?.trim() || undefined,
       });
       return {
         qrDataUrl: result.qrcodeUrl,