@openclaw-channel/socket-chat 1.0.2 → 1.0.4

package/README.md

@@ -30,6 +30,16 @@ openclaw plugins install /path/to/socket-chat
 
 ---
 
+## 通过 CLI 添加账号
+
+apiKey 从微秘书平台[个人中心](https://wechat.aibotk.com/user/info)获取
+
+```bash
+openclaw channels add --channel socket-chat --token <apiKey>
+```
+
+---
+
 ## 配置
 
 在 `~/.openclaw/config.yaml` 中添加：
@@ -39,11 +49,63 @@ channels:
   socket-chat:
     apiKey: "your-api-key"
     enabled: true
-    dmPolicy: "pairing"   # pairing | open | allowlist
-    allowFrom: []         # 允许触发 AI 的发送者 ID 白名单
-    requireMention: true  # 群组消息是否需要 @提及机器人
+
+    # DM（私聊）访问策略
+    dmPolicy: "pairing"       # pairing | open | allowlist
+    allowFrom: []             # DM 白名单（dmPolicy=allowlist/pairing 时生效）
+
+    # 群组访问策略
+    requireMention: true      # 群消息是否需要 @提及机器人
+    groupPolicy: "open"       # open | allowlist | disabled（见下方说明）
+    groups: []                # 允许的群 ID 列表（groupPolicy=allowlist 时生效）
+    groupAllowFrom: []        # 群内允许触发 AI 的发送者 ID/昵称列表
 ```
 
+### 群组访问控制
+
+群消息经过**三层**依次检查，任意一层不通过则丢弃该消息：
+
+#### 第一层：群级（哪些群允许触发 AI）
+
+| `groupPolicy` | 行为 |
+|--------------|------|
+| `open`（默认）| bot 所在所有群均可触发 |
+| `allowlist` | 仅 `groups` 列表中的群可触发；首次被拦截时向该群发一条提醒（进程内只发一次） |
+| `disabled` | 禁止所有群消息触发 AI，静默丢弃 |
+
+```yaml
+channels:
+  socket-chat:
+    groupPolicy: allowlist
+    groups:
+      - "R:10804599808581977"
+      - "R:another_group_id"
+```
+
+#### 第二层：sender 级（群内哪些人可以触发 AI）
+
+`groupAllowFrom` 为空时不限制（允许群内所有成员）。支持按 `senderId` 或 `senderName` 匹配，大小写不敏感，支持通配符 `*`。
+
+```yaml
+channels:
+  socket-chat:
+    groupAllowFrom:
+      - "wxid_123456"   # 按 senderId 精确匹配
+      - "Alice"         # 按 senderName 匹配
+      - "*"             # 允许所有成员
+```
+
+被拦截的 sender 静默丢弃，不向群发任何提示。
+
+#### 第三层：@提及检查
+
+`requireMention: true`（默认）时，群消息必须满足以下任意条件之一：
+- 平台传来 `isGroupMention: true`
+- 消息内容包含 `@{robotId}`
+
+> **注意**：媒体消息（图片、视频等）无法携带 @，若平台侧开启了 `forwardMediaMsg`，
+> 应在发布 MQTT 消息时主动将 `isGroupMention` 设为 `true`，避免被此层拦截。
+
 ### 多账号配置
 
 ```yaml
@@ -62,19 +124,19 @@ channels:
 
 | 字段 | 默认值 | 说明 |
 |------|--------|------|
+| `dmPolicy` | `pairing` | DM 访问策略：`pairing` / `open` / `allowlist` |
+| `allowFrom` | `[]` | DM 白名单，senderId 或 senderName 列表 |
+| `requireMention` | `true` | 群消息是否需要 @提及机器人 |
+| `groupPolicy` | `open` | 群访问策略：`open` / `allowlist` / `disabled` |
+| `groups` | `[]` | 允许的群 ID 列表（`groupPolicy=allowlist` 时生效） |
+| `groupAllowFrom` | `[]` | 群内允许触发 AI 的发送者 ID/昵称列表，空=不限制 |
 | `mqttConfigTtlSec` | `300` | MQTT 配置缓存时间（秒） |
 | `maxReconnectAttempts` | `10` | MQTT 断线最大重连次数 |
 | `reconnectBaseDelayMs` | `2000` | 重连基础延迟（毫秒，指数退避） |
 
 ---
 
-## 通过 CLI 添加账号
-
-```bash
-openclaw channels add socket-chat --token <apiKey>
-```
 
----
 
 ## 消息格式
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw-channel/socket-chat",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "OpenClaw Socket Chat channel plugin — MQTT-based IM bridge",
   "type": "module",
   "publishConfig": {

package/src/__sdk-stub__.ts

@@ -7,6 +7,9 @@
  */
 export { resolveAllowlistMatchByCandidates } from "../../openclaw/src/channels/allowlist-match.js";
 export { createNormalizedOutboundDeliverer } from "../../openclaw/src/plugin-sdk/reply-payload.js";
+export { buildMediaPayload } from "../../openclaw/src/channels/plugins/media-payload.js";
+export { resolveChannelMediaMaxBytes } from "../../openclaw/src/channels/plugins/media-limits.js";
+export { detectMime } from "../../openclaw/src/media/mime.js";
 
 // ---- type-only re-exports (erased at runtime) ----
 export type { ChannelGatewayContext } from "../../openclaw/src/plugin-sdk/index.js";

package/src/config-schema.ts

@@ -32,12 +32,32 @@ export const SocketChatAccountConfigSchema = z.object({
   enabled: z.boolean().optional(),
   /** DM 安全策略 */
   dmPolicy: z.enum(["pairing", "open", "allowlist"]).optional(),
-  /** 允许触发 AI 的发送者 ID 列表 */
+  /** 允许触发 AI 的发送者 ID 列表（DM 用） */
   allowFrom: z.array(z.string()).optional(),
   /** 默认发消息目标（contactId 或 group:groupId） */
   defaultTo: z.string().optional(),
   /** 群组消息是否需要 @提及 bot 才触发 */
   requireMention: z.boolean().optional(),
+  /**
+   * 群组访问策略（第一层：哪些群允许触发 AI）
+   *   - "open"（默认）：bot 所在所有群均可触发
+   *   - "allowlist"：仅 groups 列表中的群可触发
+   *   - "disabled"：禁止所有群消息触发 AI
+   */
+  groupPolicy: z.enum(["open", "allowlist", "disabled"]).optional(),
+  /**
+   * 允许触发 AI 的群 ID 列表（第一层群级白名单）
+   * groupPolicy="allowlist" 时生效；groupPolicy="open" 时忽略
+   * 示例：["R:10804599808581977", "R:xxx"]
+   */
+  groups: z.array(z.string()).optional(),
+  /**
+   * 群内允许触发 AI 的发送者 ID 列表（第二层 sender 级白名单）
+   * 不配置或为空则允许群内所有成员触发（受 requireMention 约束）
+   */
+  groupAllowFrom: z.array(z.string()).optional(),
+  /** 媒体文件大小上限（MB）。未配置时使用框架全局默认值 */
+  mediaMaxMb: z.number().optional(),
   /** MQTT 连接配置缓存 TTL（秒），默认 300 */
   mqttConfigTtlSec: z.number().optional(),
   /** MQTT 重连最大次数，默认 10 */

package/src/inbound.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, it, vi } from "vitest";
-import { handleInboundMessage } from "./inbound.js";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { handleInboundMessage, _resetNotifiedGroupsForTest } from "./inbound.js";
 import type { SocketChatInboundMessage } from "./types.js";
 import type { CoreConfig } from "./config.js";
 
@@ -40,6 +40,16 @@ type MockChannelRuntime = {
   activity: {
     record: ReturnType<typeof vi.fn>;
   };
+  channel: {
+    media: {
+      fetchRemoteMedia: ReturnType<typeof vi.fn>;
+      saveMediaBuffer: ReturnType<typeof vi.fn>;
+    };
+  };
+  media: {
+    fetchRemoteMedia: ReturnType<typeof vi.fn>;
+    saveMediaBuffer: ReturnType<typeof vi.fn>;
+  };
 };
 
 function makeMockRuntime(overrides: Partial<MockChannelRuntime> = {}): MockChannelRuntime {
@@ -72,6 +82,30 @@ function makeMockRuntime(overrides: Partial<MockChannelRuntime> = {}): MockChann
       record: vi.fn(),
       ...overrides.activity,
     },
+    channel: {
+      media: {
+        fetchRemoteMedia: vi.fn(async () => ({
+          buffer: Buffer.from("fake-image-data"),
+          contentType: "image/jpeg",
+        })),
+        saveMediaBuffer: vi.fn(async () => ({
+          path: "/tmp/openclaw/inbound/saved-img.jpg",
+          contentType: "image/jpeg",
+        })),
+        ...overrides.channel?.media,
+      },
+    },
+    media: {
+      fetchRemoteMedia: vi.fn(async () => ({
+        buffer: Buffer.from("fake-image-data"),
+        contentType: "image/jpeg",
+      })),
+      saveMediaBuffer: vi.fn(async () => ({
+        path: "/tmp/openclaw/inbound/saved-img.jpg",
+        contentType: "image/jpeg",
+      })),
+      ...overrides.media,
+    },
   };
 }
 
@@ -508,8 +542,13 @@ describe("handleInboundMessage — group messages", () => {
 // ---------------------------------------------------------------------------
 
 describe("handleInboundMessage — media messages", () => {
-  it("passes MediaUrl fields when msg has an HTTP url (image)", async () => {
+  it("downloads image URL and passes local path as MediaPath/MediaUrl", async () => {
     const runtime = makeMockRuntime();
+    runtime.media.saveMediaBuffer.mockResolvedValue({
+      path: "/tmp/openclaw/inbound/img-001.jpg",
+      contentType: "image/jpeg",
+    });
+
     const ctx = makeCtx(runtime, {
       channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
     });
@@ -518,7 +557,7 @@ describe("handleInboundMessage — media messages", () => {
       msg: makeMsg({
         type: "图片",
         url: "https://oss.example.com/img.jpg",
-        content: "【图片消息】\n文件名：img.jpg\n下载链接：https://oss.example.com/img.jpg",
+        content: "【图片消息】\n文件名：img.jpg",
       }),
       accountId: "default",
       ctx: ctx as never,
@@ -526,19 +565,36 @@ describe("handleInboundMessage — media messages", () => {
       sendReply: vi.fn(async () => {}),
     });
 
+    // fetchRemoteMedia should have been called with the original URL
+    expect(runtime.media.fetchRemoteMedia).toHaveBeenCalledWith(
+      expect.objectContaining({ url: "https://oss.example.com/img.jpg" }),
+    );
+    // saveMediaBuffer should have been called
+    expect(runtime.media.saveMediaBuffer).toHaveBeenCalledOnce();
+    // ctxPayload should carry the saved local path, not the original URL
     expect(runtime.reply.finalizeInboundContext).toHaveBeenCalledWith(
       expect.objectContaining({
-        MediaUrl: "https://oss.example.com/img.jpg",
-        MediaUrls: ["https://oss.example.com/img.jpg"],
-        MediaPath: "https://oss.example.com/img.jpg",
+        MediaPath: "/tmp/openclaw/inbound/img-001.jpg",
+        MediaUrl: "/tmp/openclaw/inbound/img-001.jpg",
+        MediaPaths: ["/tmp/openclaw/inbound/img-001.jpg"],
+        MediaUrls: ["/tmp/openclaw/inbound/img-001.jpg"],
         MediaType: "image/jpeg",
       }),
     );
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
   });
 
-  it("passes MediaUrl fields when msg has an HTTP url (video)", async () => {
+  it("downloads video URL and detects correct content type", async () => {
     const runtime = makeMockRuntime();
+    runtime.media.fetchRemoteMedia.mockResolvedValue({
+      buffer: Buffer.from("fake-video-data"),
+      contentType: "video/mp4",
+    });
+    runtime.media.saveMediaBuffer.mockResolvedValue({
+      path: "/tmp/openclaw/inbound/video-001.mp4",
+      contentType: "video/mp4",
+    });
+
     const ctx = makeCtx(runtime, {
       channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
     });
@@ -547,7 +603,7 @@ describe("handleInboundMessage — media messages", () => {
       msg: makeMsg({
         type: "视频",
         url: "https://oss.example.com/video.mp4",
-        content: "【视频消息】\n文件名：video.mp4\n下载链接：https://oss.example.com/video.mp4",
+        content: "【视频消息】",
       }),
       accountId: "default",
       ctx: ctx as never,
@@ -557,33 +613,186 @@ describe("handleInboundMessage — media messages", () => {
 
     expect(runtime.reply.finalizeInboundContext).toHaveBeenCalledWith(
       expect.objectContaining({
-        MediaUrl: "https://oss.example.com/video.mp4",
+        MediaPath: "/tmp/openclaw/inbound/video-001.mp4",
         MediaType: "video/mp4",
       }),
     );
   });
 
-  it("does NOT pass MediaUrl for base64 url (no OSS configured)", async () => {
+  it("decodes base64 data URL and saves to local file", async () => {
     const runtime = makeMockRuntime();
+    runtime.media.saveMediaBuffer.mockResolvedValue({
+      path: "/tmp/openclaw/inbound/b64-img.jpg",
+      contentType: "image/jpeg",
+    });
+
     const ctx = makeCtx(runtime, {
       channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
     });
 
+    // minimal valid JPEG-ish base64
+    const fakeBase64 = Buffer.from("fake-jpeg-bytes").toString("base64");
     await handleInboundMessage({
       msg: makeMsg({
         type: "图片",
-        url: "data:image/jpeg;base64,/9j/4AAQ...",
-        content: "【图片消息】\n文件名：img.jpg\n文件大小：12345 bytes",
+        url: `data:image/jpeg;base64,${fakeBase64}`,
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log: ctx.log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    // Should NOT call fetchRemoteMedia for data URLs
+    expect(runtime.media.fetchRemoteMedia).not.toHaveBeenCalled();
+    // Should call saveMediaBuffer with decoded buffer
+    expect(runtime.media.saveMediaBuffer).toHaveBeenCalledOnce();
+    const [savedBuf, savedMime] = runtime.media.saveMediaBuffer.mock.calls[0] as [Buffer, string];
+    expect(Buffer.isBuffer(savedBuf)).toBe(true);
+    expect(savedBuf.toString()).toBe("fake-jpeg-bytes");
+    expect(savedMime).toBe("image/jpeg");
+    // ctxPayload should carry the local path
+    expect(runtime.reply.finalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        MediaPath: "/tmp/openclaw/inbound/b64-img.jpg",
+        MediaUrl: "/tmp/openclaw/inbound/b64-img.jpg",
       }),
+    );
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("skips base64 media that exceeds maxBytes and continues dispatch", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      // 1 MB limit
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open", mediaMaxMb: 1 } },
+    });
+    const log = { ...ctx.log, warn: vi.fn() };
+
+    // ~2 MB of base64 data (each char ≈ 0.75 bytes → need > 1.4M chars)
+    const bigBase64 = "A".repeat(1_500_000);
+    await handleInboundMessage({
+      msg: makeMsg({
+        type: "图片",
+        url: `data:image/jpeg;base64,${bigBase64}`,
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("media localization failed"));
+    expect(runtime.media.saveMediaBuffer).not.toHaveBeenCalled();
+    // Dispatch still proceeds without media fields
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+    const callArg = runtime.reply.finalizeInboundContext.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(callArg).not.toHaveProperty("MediaPath");
+  });
+
+  it("does not call fetchRemoteMedia for base64 data URLs (uses saveMediaBuffer directly)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
+    });
+
+    const fakeBase64 = Buffer.from("img-bytes").toString("base64");
+    await handleInboundMessage({
+      msg: makeMsg({
+        type: "图片",
+        url: `data:image/jpeg;base64,${fakeBase64}`,
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log: ctx.log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    expect(runtime.media.fetchRemoteMedia).not.toHaveBeenCalled();
+    expect(runtime.media.saveMediaBuffer).toHaveBeenCalledOnce();
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("does not call fetchRemoteMedia when url is absent", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
+    });
+
+    await handleInboundMessage({
+      msg: makeMsg({ content: "plain text, no media" }),
       accountId: "default",
       ctx: ctx as never,
       log: ctx.log,
       sendReply: vi.fn(async () => {}),
     });
 
+    expect(runtime.media.fetchRemoteMedia).not.toHaveBeenCalled();
+    expect(runtime.media.saveMediaBuffer).not.toHaveBeenCalled();
     const callArg = runtime.reply.finalizeInboundContext.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(callArg).not.toHaveProperty("MediaPath");
+  });
+
+  it("continues dispatch and logs warning when media download fails", async () => {
+    const runtime = makeMockRuntime();
+    runtime.media.fetchRemoteMedia.mockRejectedValue(new Error("network timeout"));
+
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
+    });
+    const log = { ...ctx.log, warn: vi.fn() };
+
+    await handleInboundMessage({
+      msg: makeMsg({
+        type: "图片",
+        url: "https://oss.example.com/img.jpg",
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    // Warning logged
+    expect(log.warn).toHaveBeenCalledWith(
+      expect.stringContaining("media localization failed"),
+    );
+    // Dispatch still proceeds (text body)
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+    // No media fields in ctxPayload
+    const callArg = runtime.reply.finalizeInboundContext.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(callArg).not.toHaveProperty("MediaPath");
     expect(callArg).not.toHaveProperty("MediaUrl");
-    expect(callArg).not.toHaveProperty("MediaUrls");
+  });
+
+  it("continues dispatch and logs warning when saveMediaBuffer fails", async () => {
+    const runtime = makeMockRuntime();
+    runtime.media.saveMediaBuffer.mockRejectedValue(new Error("disk full"));
+
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
+    });
+    const log = { ...ctx.log, warn: vi.fn() };
+
+    await handleInboundMessage({
+      msg: makeMsg({
+        type: "图片",
+        url: "https://oss.example.com/img.jpg",
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    expect(log.warn).toHaveBeenCalledWith(
+      expect.stringContaining("media localization failed"),
+    );
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
   });
 
@@ -605,7 +814,6 @@ describe("handleInboundMessage — media messages", () => {
       sendReply: vi.fn(async () => {}),
     });
 
-    // Should not be skipped — dispatches even without text content
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
   });
 
@@ -666,6 +874,7 @@ describe("handleInboundMessage — media messages", () => {
     });
 
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(runtime.media.fetchRemoteMedia).not.toHaveBeenCalled();
   });
 });
 
@@ -737,3 +946,175 @@ describe("handleInboundMessage — edge cases", () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// Group access control — tier 1 (groupId) + tier 2 (sender)
+// ---------------------------------------------------------------------------
+
+describe("handleInboundMessage — group access control (tier 1: groupId)", () => {
+  beforeEach(() => {
+    _resetNotifiedGroupsForTest();
+  });
+
+  it("allows all groups when groupPolicy=open (default)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:any_group", robotId: "robot_abc", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("blocks all groups when groupPolicy=disabled (no notification)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "disabled" } },
+    });
+    const sendReply = vi.fn(async () => {});
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:any_group", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(sendReply).not.toHaveBeenCalled();
+  });
+
+  it("allows group in allowlist when groupPolicy=allowlist", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: {
+        "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["R:allowed_group"], requireMention: false },
+      },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:allowed_group", robotId: "robot_abc", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("blocks unlisted group without sending notification (notify branch commented out)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["R:allowed_group"] } },
+    });
+    const sendReply = vi.fn(async () => {});
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:other_group", groupName: "测试群", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    // Notification is currently disabled (commented out in inbound.ts)
+    expect(sendReply).not.toHaveBeenCalled();
+  });
+
+  it("silently blocks repeated messages from same unlisted group", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["R:allowed_group"] } },
+    });
+    const sendReply = vi.fn(async () => {});
+    const msg = makeMsg({ isGroup: true, groupId: "R:notify_once_group", isGroupMention: true });
+    await handleInboundMessage({ msg, accountId: "default", ctx: ctx as never, log: ctx.log, sendReply });
+    await handleInboundMessage({ msg, accountId: "default", ctx: ctx as never, log: ctx.log, sendReply });
+    expect(sendReply).not.toHaveBeenCalled();
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+  });
+
+  it("blocks when groupPolicy=allowlist and groups is empty (no notification)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: [] } },
+    });
+    const sendReply = vi.fn(async () => {});
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:any_group", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(sendReply).not.toHaveBeenCalled();
+  });
+
+  it("allows wildcard '*' in groups list", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["*"], requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:any_group", robotId: "robot_abc", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+});
+
+describe("handleInboundMessage — group access control (tier 2: sender)", () => {
+  beforeEach(() => {
+    _resetNotifiedGroupsForTest();
+  });
+
+  it("allows all senders when groupAllowFrom is empty", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_anyone", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("allows sender matching groupAllowFrom by ID", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupAllowFrom: ["wxid_allowed"], requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_allowed", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("allows sender matching groupAllowFrom by name (case-insensitive)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupAllowFrom: ["alice"], requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_unknown", senderName: "Alice", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("blocks sender not in groupAllowFrom (silent drop)", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupAllowFrom: ["wxid_allowed"], requireMention: false } },
+    });
+    const sendReply = vi.fn(async () => {});
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_stranger", senderName: "Stranger", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(sendReply).not.toHaveBeenCalled();
+  });
+
+  it("allows wildcard '*' in groupAllowFrom", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupAllowFrom: ["*"], requireMention: false } },
+    });
+    await handleInboundMessage({
+      msg: makeMsg({ isGroup: true, groupId: "R:g1", senderId: "wxid_anyone", isGroupMention: true }),
+      accountId: "default", ctx: ctx as never, log: ctx.log, sendReply: vi.fn(async () => {}),
+    });
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+});

package/src/inbound.ts

@@ -1,5 +1,11 @@
 import type { ChannelGatewayContext } from "openclaw/plugin-sdk";
-import { resolveAllowlistMatchByCandidates, createNormalizedOutboundDeliverer } from "openclaw/plugin-sdk";
+import {
+  resolveAllowlistMatchByCandidates,
+  createNormalizedOutboundDeliverer,
+  buildMediaPayload,
+  resolveChannelMediaMaxBytes,
+  detectMime,
+} from "openclaw/plugin-sdk";
 import { resolveSocketChatAccount, type CoreConfig } from "./config.js";
 import type { ResolvedSocketChatAccount } from "./config.js";
 import type { SocketChatInboundMessage } from "./types.js";
@@ -113,6 +119,114 @@ async function enforceDmAccess(params: {
   return false;
 }
 
+// ---------------------------------------------------------------------------
+// 群组访问控制 — 第一层（groupId 级别）+ 第二层（sender 级别）
+// ---------------------------------------------------------------------------
+
+/**
+ * 记录已发送过"群未授权"提醒的群，键为 `${accountId}:${groupId}`。
+ * 进程内只提醒一次，避免每条消息都重复发送。
+ */
+const notifiedGroups = new Set<string>();
+
+/** 仅供测试使用：重置一次性提醒状态。 */
+export function _resetNotifiedGroupsForTest(): void {
+  notifiedGroups.clear();
+}
+
+/**
+ * 规范化群/发送者 ID，去除前缀、空格、转小写，便于白名单对比。
+ */
+function normalizeSocketChatId(raw: string): string {
+  return raw.replace(/^(socket-chat|sc):/i, "").trim().toLowerCase();
+}
+
+/**
+ * 第一层：检查当前群是否被允许触发 AI。
+ *
+ * - groupPolicy="open"（默认）：所有群均可触发
+ * - groupPolicy="allowlist"：仅 groups 列表中的群可触发，不在列表的群收到一次提醒
+ * - groupPolicy="disabled"：禁止所有群消息触发 AI
+ *
+ * 返回 `{ allowed, notify }`:
+ *   - allowed=false + notify=true 表示首次拦截，调用方应发送提醒消息
+ *   - allowed=false + notify=false 表示已提醒过，静默忽略
+ */
+function checkGroupAccess(params: {
+  groupId: string;
+  account: ResolvedSocketChatAccount;
+  log: LogSink;
+  accountId: string;
+}): { allowed: boolean; notify: boolean } {
+  const { groupId, account, log, accountId } = params;
+  const groupPolicy = account.config.groupPolicy ?? "open";
+
+  if (groupPolicy === "disabled") {
+    log.info(`[${accountId}] group msg blocked (groupPolicy=disabled)`);
+    return { allowed: false, notify: false };
+  }
+
+  if (groupPolicy === "open") {
+    return { allowed: true, notify: false };
+  }
+
+  // allowlist：检查 groupId 是否在 groups 名单中
+  const groups = (account.config.groups ?? []).map(normalizeSocketChatId);
+  if (groups.length === 0) {
+    log.info(`[${accountId}] group ${groupId} blocked (groupPolicy=allowlist, groups is empty)`);
+    return { allowed: false, notify: false };
+  }
+
+  const normalizedGroupId = normalizeSocketChatId(groupId);
+  if (groups.includes("*") || groups.includes(normalizedGroupId)) {
+    return { allowed: true, notify: false };
+  }
+
+  log.info(`[${accountId}] group ${groupId} not in groups allowlist (groupPolicy=allowlist)`);
+
+  // 判断是否需要发送一次性提醒
+  const notifyKey = `${accountId}:${groupId}`;
+  if (notifiedGroups.has(notifyKey)) {
+    return { allowed: false, notify: false };
+  }
+  notifiedGroups.add(notifyKey);
+  return { allowed: false, notify: true };
+}
+
+/**
+ * 第二层：检查群内发送者是否被允许触发 AI。
+ *
+ * 仅当 groupAllowFrom 非空时生效；为空则允许群内所有成员。
+ */
+function checkGroupSenderAccess(params: {
+  senderId: string;
+  senderName: string | undefined;
+  account: ResolvedSocketChatAccount;
+  log: LogSink;
+  accountId: string;
+}): boolean {
+  const { senderId, senderName, account, log, accountId } = params;
+  const groupAllowFrom = (account.config.groupAllowFrom ?? []).map(normalizeSocketChatId);
+
+  // 未配置 sender 白名单 → 不限制
+  if (groupAllowFrom.length === 0) return true;
+  if (groupAllowFrom.includes("*")) return true;
+
+  const normalizedSenderId = normalizeSocketChatId(senderId);
+  const normalizedSenderName = senderName ? senderName.trim().toLowerCase() : undefined;
+
+  const allowed =
+    groupAllowFrom.includes(normalizedSenderId) ||
+    (normalizedSenderName !== undefined && groupAllowFrom.includes(normalizedSenderName));
+
+  if (!allowed) {
+    log.info(
+      `[${accountId}] group sender ${senderId} not in groupAllowFrom`,
+    );
+  }
+  return allowed;
+}
+
 // ---------------------------------------------------------------------------
 // 群组消息 @提及检查
 // ---------------------------------------------------------------------------
@@ -166,8 +280,9 @@ type LogSink = {
  * 处理 MQTT 入站消息：
  * 1. 安全策略检查（allowlist / pairing）
  * 2. 群组 @提及检查
- * 3. 路由 + 记录 session
- * 4. 派发 AI 回复
+ * 3. 媒体文件下载到本地
+ * 4. 路由 + 记录 session
+ * 5. 派发 AI 回复
  */
 export async function handleInboundMessage(params: {
   msg: SocketChatInboundMessage;
@@ -208,7 +323,34 @@ export async function handleInboundMessage(params: {
     return;
   }
 
-  // ---- 2. 群组 @提及检查 ----
+  // ---- 2. 群组访问控制（第一层：群级 + 第二层：sender 级）----
+  if (msg.isGroup) {
+    const groupId = msg.groupId ?? msg.senderId;
+
+    // 第一层：groupId 是否在允许列表中
+    const groupAccess = checkGroupAccess({ groupId, account, log, accountId });
+    if (!groupAccess.allowed) {
+      // if (groupAccess.notify) {
+      //   await sendReply(
+      //     `group:${groupId}`,
+      //     `此群（${msg.groupName ?? groupId}）未获授权使用 AI 服务。如需开启，请联系管理员将群 ID "${groupId}" 加入 groups 配置。`,
+      //   );
+      // }
+      return;
+    }
+
+    // 第二层：群内发送者是否被允许
+    const senderAccessAllowed = checkGroupSenderAccess({
+      senderId: msg.senderId,
+      senderName: msg.senderName,
+      account,
+      log,
+      accountId,
+    });
+    if (!senderAccessAllowed) return;
+  }
+
+  // ---- 3. 群组 @提及检查 ----
   // robotId 从 MQTT config 传入（由 mqtt-client.ts 调用时提供）
   // 此处从 msg.robotId 字段取（平台在每条消息中会带上 robotId）
   const mentionAllowed = checkGroupMention({
@@ -226,13 +368,78 @@ export async function handleInboundMessage(params: {
   const peerId = msg.isGroup ? (msg.groupId ?? msg.senderId) : msg.senderId;
 
   // 判断是否为媒体消息（图片/视频/文件等）
-  const mediaUrl = msg.url && !msg.url.startsWith("data:") ? msg.url : undefined;
-  // base64 内容不传给 agent（避免超长），仅标记 placeholder
   const isMediaMsg = !!msg.type && msg.type !== "文字";
   // BodyForAgent：媒体消息在 content 中已包含描述文字（如"【图片消息】\n下载链接：..."），直接使用
   const body = msg.content?.trim() || (isMediaMsg ? `<media:${msg.type}>` : "");
 
-  // ---- 3. 路由 ----
+  // ---- 3. 媒体文件本地化 ----
+  // 将媒体 URL 下载到本地，让 agent 能直接读取文件而不依赖外部 URL 的可用性。
+  // HTTP/HTTPS URL：通过 fetchRemoteMedia 下载；data: URL：直接解码 base64。
+  let resolvedMediaPayload = {};
+  const mediaUrl = msg.url?.trim();
+  if (mediaUrl) {
+    try {
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg: ctx.cfg,
+        resolveChannelLimitMb: ({ cfg }) =>
+          (cfg as CoreConfig).channels?.["socket-chat"]?.mediaMaxMb,
+        accountId,
+      });
+
+      let buffer: Buffer;
+      let contentTypeHint: string | undefined;
+
+      if (mediaUrl.startsWith("data:")) {
+        // data URL：解析 MIME 和 base64 载荷
+        const commaIdx = mediaUrl.indexOf(",");
+        const meta = commaIdx > 0 ? mediaUrl.slice(5, commaIdx) : "";
+        const base64Data = commaIdx > 0 ? mediaUrl.slice(commaIdx + 1) : "";
+        contentTypeHint = meta.split(";")[0] || undefined;
+
+        // 大小预检（base64 字节数 × 0.75 ≈ 原始字节数）
+        const estimatedBytes = Math.ceil(base64Data.length * 0.75);
+        if (maxBytes && estimatedBytes > maxBytes) {
+          log.warn(
+            `[${accountId}] base64 media too large for ${msg.messageId} (est. ${estimatedBytes} bytes, limit ${maxBytes})`,
+          );
+          throw new Error("base64 media exceeds maxBytes limit");
+        }
+
+        buffer = Buffer.from(base64Data, "base64");
+      } else {
+        // HTTP/HTTPS URL：通过网络下载
+        const fetched = await channelRuntime.media.fetchRemoteMedia({
+          url: mediaUrl,
+          filePathHint: mediaUrl,
+          maxBytes,
+        });
+        buffer = fetched.buffer;
+        contentTypeHint = fetched.contentType;
+      }
+
+      const mime = await detectMime({
+        buffer,
+        headerMime: contentTypeHint,
+        filePath: mediaUrl,
+      });
+      const saved = await channelRuntime.media.saveMediaBuffer(
+        buffer,
+        mime ?? contentTypeHint,
+        "inbound",
+        maxBytes,
+      );
+      resolvedMediaPayload = buildMediaPayload([
+        { path: saved.path, contentType: saved.contentType },
+      ]);
+    } catch (err) {
+      // 下载/解码失败不阻断消息处理，仍正常派发文字部分
+      log.warn(
+        `[${accountId}] media localization failed for ${msg.messageId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // ---- 4. 路由 ----
   const route = channelRuntime.routing.resolveAgentRoute({
     cfg: ctx.cfg,
     channel: "socket-chat",
@@ -247,7 +454,7 @@ export async function handleInboundMessage(params: {
     `[${accountId}] dispatch ${msg.messageId} from ${msg.senderId} → agent ${route.agentId}`,
   );
 
-  // ---- 4. 构建 MsgContext ----
+  // ---- 5. 构建 MsgContext ----
   const fromLabel = msg.isGroup
     ? `socket-chat:room:${peerId}`
     : `socket-chat:${msg.senderId}`;
@@ -261,15 +468,7 @@ export async function handleInboundMessage(params: {
     RawBody: msg.content || (msg.url ?? ""),
     BodyForAgent: body,
     CommandBody: body,
-    ...(mediaUrl
-      ? {
-          MediaUrl: mediaUrl,
-          MediaUrls: [mediaUrl],
-          MediaPath: mediaUrl,
-          // 尽量从 type 推断 MIME，否则留空由框架处理
-          MediaType: msg.type === "图片" ? "image/jpeg" : msg.type === "视频" ? "video/mp4" : undefined,
-        }
-      : {}),
+    ...resolvedMediaPayload,
     From: fromLabel,
     To: toLabel,
     SessionKey: route.sessionKey,
@@ -290,7 +489,7 @@ export async function handleInboundMessage(params: {
   });
 
   try {
-    // ---- 5. 记录 session 元数据 ----
+    // ---- 6. 记录 session 元数据 ----
     const storePath = channelRuntime.session.resolveStorePath(undefined, {
       agentId: route.agentId,
     });
@@ -310,7 +509,7 @@ export async function handleInboundMessage(params: {
       direction: "inbound",
     });
 
-    // ---- 6. 派发 AI 回复 ----
+    // ---- 7. 派发 AI 回复 ----
     // deliver 负责实际发送：框架当 originatingChannel === currentSurface 时
     // 不走 outbound adapter，直接调用此函数投递回复。
     const deliverReply = createNormalizedOutboundDeliverer(async (payload) => {