@core-workspace/infoflow-openclaw-plugin 2026.3.8 → 2026.3.27-beta.0

package/README.md

@@ -14,6 +14,7 @@
 - [配置](#配置)
 - [插件架构](#插件架构)
 - [开发指南](#开发指南)
+- [内置命令](#内置命令)
 - [扩展：Agent Tools](#扩展-agent-tools)
 - [扩展：Agent Hooks](#扩展-agent-hooks)
 - [扩展：Agent Skills](#扩展-agent-skills)
@@ -70,8 +71,8 @@ npm install
   "channels": {
     "infoflow": {
       "connectionMode": "websocket",
-      "wsGateway": "infoflow-open-gateway.weiyun.baidu.com",
-      "apiHost": "https://apiin.im.baidu.com",
+      "wsGateway": "infoflow-open-gateway.baidu.com",
+      "apiHost": "https://api.im.baidu.com",
       "appKey": "填你的 appKey",
       "appSecret": "填你的 appSecret",
       "checkToken": "填你的 checkToken",
@@ -132,7 +133,7 @@ openclaw directory groups infoflow
 {
   channels: {
     infoflow: {
-      apiHost: "https://apiin.im.baidu.com",
+      apiHost: "https://api.im.baidu.com",
       checkToken: "your-check-token",
       encodingAESKey: "your-encoding-aes-key",
       appKey: "your-app-key",
@@ -150,9 +151,9 @@ openclaw directory groups infoflow
     infoflow: {
       // ── 基础连接 ──────────────────────────────────────────
       enabled: true,
-      apiHost: "https://apiin.im.baidu.com",          // 如流 API 地址（必填）
+      apiHost: "https://api.im.baidu.com",          // 如流 API 地址（必填）
       connectionMode: "websocket",                      // "webhook"（默认）或 "websocket"
-      wsGateway: "infoflow-open-gateway.weiyun.baidu.com", // WebSocket 网关（websocket 模式专用）
+      wsGateway: "infoflow-open-gateway.baidu.com", // WebSocket 网关（websocket 模式专用）
       checkToken: "your-check-token",                   // 消息验签 Token（必填）
       encodingAESKey: "your-encoding-aes-key",          // 消息 AES 加密密钥（必填）
       appKey: "your-app-key",                           // 应用 Key（必填）
@@ -190,8 +191,13 @@ openclaw directory groups infoflow
       groups: {
         "12345678": {
           replyMode: "proactive",
+          groupSessionMode: "user", // 此群按群+人拆分会话
           systemPrompt: "你是该群的专属助手，回答要简洁。",
         },
+        "87654321": {
+          replyMode: "record", // 此群仅记录不回复
+          groupSessionMode: "group", // 此群按群拆分会话
+        },
       },
     },
   },
@@ -220,7 +226,7 @@ https://your-domain/webhook/infoflow
   channels: {
     infoflow: {
       connectionMode: "websocket",
-      // wsGateway: "infoflow-open-gateway.weiyun.baidu.com",  // 可选，默认值
+      // wsGateway: "infoflow-open-gateway.baidu.com",  // 可选，默认值
     },
   },
 }
@@ -234,15 +240,15 @@ https://your-domain/webhook/infoflow
 
 | 字段 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|:----:|--------|------|
-| `apiHost` | `string` | ✅ | — | 如流 API 地址，例如 `https://apiin.im.baidu.com` |
-| `checkToken` | `string` | ✅ | — | 消息验签 Token，从如流企业后台获取 |
-| `encodingAESKey` | `string` | ✅ | — | 消息 AES 加密密钥，从如流企业后台获取 |
+| `apiHost` | `string` | ✅ | — | 如流 API 地址，例如 `https://api.im.baidu.com` |
+| `checkToken` | `string` | — | — | 消息验签 Token，从如流企业后台获取（**webhook 模式必填**）|
+| `encodingAESKey` | `string` | — | — | 消息 AES 加密密钥，从如流企业后台获取（**webhook 模式必填**）|
 | `appKey` | `string` | ✅ | — | 应用 Key，从如流企业后台获取 |
 | `appSecret` | `string` | ✅ | — | 应用 Secret，从如流企业后台获取 |
 | `appAgentId` | `number` | — | — | 企业后台"应用ID"（数字），私聊消息撤回需要此字段 |
-| `robotName` | `string` | — | — | 机器人在群里的显示名称，用于检测消息中的 @ 提及 |
+| `robotName` | `string` | — | — | 机器人在群里的显示名称，用于检测消息中的 @ 提及。**未配置时无法识别 @机器人，`mention-only` / `mention-and-watch` 模式将退化为对所有群消息触发** |
 | `connectionMode` | `string` | — | `"webhook"` | 消息接收方式：`"webhook"` 如流主动推送；`"websocket"` 插件主动长连接 |
-| `wsGateway` | `string` | — | `"infoflow-open-gateway.weiyun.baidu.com"` | WebSocket 网关域名，仅 `websocket` 模式使用 |
+| `wsGateway` | `string` | — | `"infoflow-open-gateway.baidu.com"` | WebSocket 网关域名，仅 `websocket` 模式使用 |
 | `enabled` | `boolean` | — | `true` | 是否启用该插件 |
 
 #### 访问控制
@@ -260,6 +266,7 @@ https://your-domain/webhook/infoflow
 | 字段 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|:----:|--------|------|
 | `replyMode` | `string` | — | `"mention-and-watch"` | 群聊回复策略：`ignore`（丢弃）/ `record`（仅记录）/ `mention-only`（仅被@时）/ `mention-and-watch`（被@或关注人被@时）/ `proactive`（主动参与） |
+| `groupSessionMode` | `string` | — | `"group"` | 群聊会话拆分模式：`"group"` = 按群拆分；`"user"` = 按群+人拆分 |
 | `followUp` | `boolean` | — | `true` | 机器人回复后，时间窗口内自动识别追问，无需再次 @ |
 | `followUpWindow` | `number` | — | `300` | 跟进时间窗口（秒） |
 | `watchMentions` | `string[]` | — | `[]` | 监控指定人员被 @，机器人作为其助手代为判断是否回答，填写 uuapName |
@@ -271,6 +278,7 @@ https://your-domain/webhook/infoflow
 |------|------|:----:|--------|------|
 | `dmMessageFormat` | `string` | — | `"text"` | 私聊发出消息的格式：`"text"` 纯文本；`"markdown"` 富文本，支持标题/加粗/列表 |
 | `groupMessageFormat` | `string` | — | `"text"` | 群聊发出消息的格式：`"text"` 纯文本；`"markdown"` 富文本。**注意：`markdown` 格式不支持引用回复** |
+| `textChunkLimit` | `number` | — | `1800` | 长消息自动分片的每片最大字符数，超出部分拆成多条消息发送 |
 | `processingHint` | `boolean` | — | `true` | LLM 响应较慢时，提前发送"⏳ 处理中..."提示；出错时发"处理出错，请稍后重试" |
 | `processingHintDelay` | `number` | — | `5` | 发送"⏳ 处理中..."前等待的秒数；LLM 在此时间内响应则不发；设为 `0` 立即发送 |
 
@@ -289,6 +297,7 @@ https://your-domain/webhook/infoflow
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `replyMode` | `string` | 覆盖该群的回复策略 |
+| `groupSessionMode` | `string` | 覆盖该群的会话拆分模式：`"group"` = 按群拆分；`"user"` = 按群+人拆分 |
 | `watchMentions` | `string[]` | 覆盖该群监控的人员列表 |
 | `watchRegex` | `string` | 覆盖该群的正则匹配规则 |
 | `followUp` | `boolean` | 覆盖该群的跟进开关 |
@@ -307,55 +316,66 @@ https://your-domain/webhook/infoflow
 
 | 模块 | 文件 | 功能 |
 |------|------|------|
-| **插件入口** | `index.ts` | 注册 Channel、Webhook 路由、Tools、Hooks |
-| **Channel 定义** | `src/channel.ts` | 插件结构、生命周期、Actions |
-| **消息接收(Webhook)** | `src/inbound/webhook-parser.ts` | Webhook 解析、解密、去重 |
-| **消息接收(WebSocket)** | `src/inbound/ws-receiver.ts` | WebSocket 长连接 |
-| **接入管理** | `src/inbound/monitor.ts` | Webhook/WebSocket 启动管理 |
-| **消息处理** | `src/inbound/message-handler.ts` | replyMode 决策、历史注入、LLM 调用 |
-| **消息发送** | `src/outbound/send.ts` | 私聊/群聊发送 API |
-| **回复分发** | `src/outbound/reply-dispatcher.ts` | @mentions 解析、分块、引用回复构造 |
-| **图片处理** | `src/outbound/media.ts` | 图片下载、压缩、Base64（含 SSRF 防护） |
-| **Actions** | `src/outbound/actions.ts` | Channel Actions（send/delete，供 LLM 通过 Channel 调用） |
+| **插件入口** | `index.ts` | 注册 Channel、Webhook 路由、Tools、Hooks、Commands |
+| **Channel 定义** | `src/channel/channel.ts` | 插件结构、生命周期、Actions |
+| **消息接收(Webhook)** | `src/adapter/inbound/webhook-parser.ts` | Webhook 解析、解密、去重 |
+| **消息接收(WebSocket)** | `src/adapter/inbound/ws-receiver.ts` | WebSocket 长连接 |
+| **接入管理** | `src/channel/monitor.ts` | Webhook/WebSocket 启动管理 |
+| **消息处理** | `src/handler/message-handler.ts` | replyMode 决策、历史注入、LLM 调用 |
+| **消息发送** | `src/channel/outbound.ts` | 私聊/群聊发送 API |
+| **回复分发** | `src/adapter/outbound/reply-dispatcher.ts` | @mentions 解析、分块、引用回复构造 |
+| **图片处理** | `src/channel/media.ts` | 图片下载、压缩、Base64（含 SSRF 防护） |
+| **Actions** | `src/tools/actions/index.ts` | Channel Actions（send/delete，供 LLM 通过 Channel 调用） |
 | **Agent Tools** | `src/tools/index.ts` | `infoflow_send` / `infoflow_recall`（LLM Function Calling） |
-| **Agent Hooks** | `src/hooks/index.ts` | `before_agent_start` 钩子（如流平台背景知识注入） |
-| **多账号** | `src/config/accounts.ts` | 账号解析、配置合并 |
-| **SDK 适配** | `src/sdk/token-adapter.ts` | Token 管理，封装 SDK TokenManager |
-| **消息存储** | `src/outbound/message-store.ts` | 已发送消息记录（支持撤回） |
+| **Agent Hooks** | `src/tools/hooks/index.ts` | `before_agent_start` 钩子（如流平台背景知识注入） |
+| **多账号** | `src/channel/accounts.ts` | 账号解析、配置合并 |
+| **SDK 适配** | `src/utils/token-adapter.ts` | Token 管理，封装 SDK TokenManager |
+| **消息存储** | `src/utils/store/message-store.ts` | 已发送消息记录（支持撤回） |
+| **安全策略** | `src/security/dm-policy.ts` | 私聊权限策略 |
+| **群聊策略** | `src/security/group-policy.ts` | 群组权限、replyMode、followUp |
+| **内置命令** | `src/commands/doctor.ts` | `/infoflow-doctor` 自检命令 |
+| **内置命令** | `src/commands/logs.ts` | `/infoflow-logs` 日志查看命令 |
 
 ### 项目结构
 
 ```
-infoflow-openclaw/
-├── index.ts                          # 插件入口
-├── openclaw.plugin.json              # 插件元数据
-├── skills/                           # 随插件分发的 skill 包
-│   └── infoflow-dev/                 # 如流开发者指南 skill
+openclaw_infoflow/
+├── index.ts                              # 插件入口
+├── openclaw.plugin.json                  # 插件元数据
+├── skills/
+│   └── infoflow-dev/                     # 如流开发者指南 skill
 ├── src/
-│   ├── channel.ts
-│   ├── logging.ts
-│   ├── runtime.ts
-│   ├── types.ts
-│   ├── config/
-│   │   └── accounts.ts
-│   ├── inbound/
-│   │   ├── monitor.ts
-│   │   ├── webhook-parser.ts
-│   │   ├── ws-receiver.ts
-│   │   └── message-handler.ts
-│   ├── outbound/
-│   │   ├── send.ts
-│   │   ├── reply-dispatcher.ts
-│   │   ├── media.ts
-│   │   ├── actions.ts
-│   │   ├── message-store.ts
-│   │   └── target-resolver.ts
+│   ├── types.ts                          # 类型定义
+│   ├── runtime.ts                        # 插件运行时单例
+│   ├── logging.ts                        # 日志模块
+│   ├── channel/
+│   │   ├── channel.ts                    # Channel 插件定义
+│   │   ├── accounts.ts                   # 多账号解析
+│   │   ├── monitor.ts                    # Webhook/WS 启动管理
+│   │   ├── outbound.ts                   # 消息发送 API
+│   │   └── media.ts                      # 图片处理
+│   ├── adapter/
+│   │   ├── inbound/
+│   │   │   ├── webhook-parser.ts         # Webhook 解析解密
+│   │   │   └── ws-receiver.ts            # WebSocket 长连接
+│   │   └── outbound/
+│   │       ├── reply-dispatcher.ts       # 回复分发（分片/@mention/引用）
+│   │       └── target-resolver.ts        # 目标地址解析
+│   ├── handler/
+│   │   └── message-handler.ts            # 消息处理核心（replyMode 决策）
+│   ├── security/
+│   │   ├── dm-policy.ts                  # 私聊权限策略
+│   │   └── group-policy.ts               # 群聊策略 + followUp
 │   ├── tools/
-│   │   └── index.ts
-│   ├── hooks/
-│   │   └── index.ts
-│   └── sdk/
-│       └── token-adapter.ts
+│   │   ├── index.ts                      # infoflow_send / infoflow_recall
+│   │   ├── actions/index.ts              # Channel Actions
+│   │   └── hooks/index.ts                # Agent Hooks
+│   ├── commands/
+│   │   ├── doctor.ts                     # /infoflow-doctor
+│   │   └── logs.ts                       # /infoflow-logs
+│   └── utils/
+│       ├── token-adapter.ts              # SDK Token 适配
+│       └── store/message-store.ts        # 已发消息存储
 └── README.md
 ```
 
@@ -397,6 +417,46 @@ tail -200 ~/.openclaw/logs/gateway.log | grep "sendInfoflowMessage"
 
 ---
 
+<a id="内置命令"></a>
+
+## 内置命令
+
+插件注册了两个可在如流中直接发送的内置命令。
+
+### /infoflow-doctor — 自检
+
+一键检查插件配置与 API 连通性，帮助排查收不到消息的问题。
+
+**在如流私聊或群聊中发送：**
+```
+/infoflow-doctor
+```
+
+**自检项：**
+1. 账号配置完整性（appKey、appSecret、checkToken 等）
+2. Access Token 获取（实际调用 Infoflow API）
+3. 发私聊测试消息
+4. 发群聊测试消息（仅在群中触发时执行）
+5. 发图片测试消息
+
+### /infoflow-logs — 日志查看
+
+查看 Infoflow 最近的收发消息日志，方便排查消息丢失、发送失败等问题。
+
+**用法：**
+
+```
+/infoflow-logs          # 最近 50 条
+/infoflow-logs 100      # 最近 100 条（最大 200）
+/infoflow-logs 50-100   # 往前翻页：跳过最近 50 条，再往前看 50 条
+```
+
+**日志来源：** `/tmp/openclaw/openclaw-YYYY-MM-DD.log`（优先今日，降级昨日）
+
+**输出上限：** 20,000 字符，超出时自动丢弃最老的条目。长输出由框架自动拆成多条消息发送。
+
+---
+
 <a id="扩展-agent-tools"></a>
 
 ## 扩展：Agent Tools
@@ -559,8 +619,9 @@ description: Skill 描述，说明何时触发（这是触发机制，写清楚
    ```bash
    tail -200 ~/.openclaw/logs/gateway.log | grep "webhook"
    ```
-3. 检查 `robotName` 是否与如流后台一致（影响 @ 检测）
+3. 检查 `robotName` 是否与如流后台机器人显示名一致（影响 @mention 检测）。**注意：不配置 `robotName` 时，`mention-only` / `mention-and-watch` 模式将退化为对所有群消息触发，而非完全不触发**
 4. 检查 `groupPolicy` 是否允许该群
+5. 在如流中发送 `/infoflow-doctor` 进行自检
 
 ### 3. 消息撤回失败？
 
@@ -596,6 +657,7 @@ Baidu Infoflow enterprise messaging platform — OpenClaw channel plugin. Suppor
 - [Configuration](#configuration)
 - [Architecture](#architecture)
 - [Development Guide](#development-guide)
+- [Built-in Commands](#built-in-commands)
 - [Extending: Agent Tools](#extending-agent-tools)
 - [Extending: Agent Hooks](#extending-agent-hooks)
 - [Extending: Agent Skills](#extending-agent-skills)
@@ -651,8 +713,8 @@ Open `~/.openclaw/openclaw.json` and add the infoflow channel config:
   "channels": {
     "infoflow": {
       "connectionMode": "websocket",
-      "wsGateway": "infoflow-open-gateway.weiyun.baidu.com",
-      "apiHost": "https://apiin.im.baidu.com",
+      "wsGateway": "infoflow-open-gateway.baidu.com",
+      "apiHost": "https://api.im.baidu.com",
       "appKey": "your-app-key",
       "appSecret": "your-app-secret",
       "checkToken": "your-check-token",
@@ -688,7 +750,7 @@ For more options (access control, group policies, message format, etc.) see [Con
 {
   channels: {
     infoflow: {
-      apiHost: "https://apiin.im.baidu.com",
+      apiHost: "https://api.im.baidu.com",
       checkToken: "your-check-token",
       encodingAESKey: "your-encoding-aes-key",
       appKey: "your-app-key",
@@ -706,9 +768,9 @@ For more options (access control, group policies, message format, etc.) see [Con
     infoflow: {
       // ── Connection ────────────────────────────────────────
       enabled: true,
-      apiHost: "https://apiin.im.baidu.com",           // required
+      apiHost: "https://api.im.baidu.com",           // required
       connectionMode: "websocket",                       // "webhook" (default) or "websocket"
-      wsGateway: "infoflow-open-gateway.weiyun.baidu.com", // websocket mode only
+      wsGateway: "infoflow-open-gateway.baidu.com", // websocket mode only
       checkToken: "your-check-token",                    // required
       encodingAESKey: "your-encoding-aes-key",           // required
       appKey: "your-app-key",                            // required
@@ -772,7 +834,7 @@ https://your-domain/webhook/infoflow
   channels: {
     infoflow: {
       connectionMode: "websocket",
-      // wsGateway: "infoflow-open-gateway.weiyun.baidu.com",  // optional
+      // wsGateway: "infoflow-open-gateway.baidu.com",  // optional
     },
   },
 }
@@ -784,15 +846,15 @@ https://your-domain/webhook/infoflow
 
 | Field | Type | Required | Default | Description |
 |-------|------|:--------:|---------|-------------|
-| `apiHost` | `string` | ✅ | — | Infoflow API host, e.g. `https://apiin.im.baidu.com` |
-| `checkToken` | `string` | ✅ | — | Message verification token from Infoflow enterprise console |
-| `encodingAESKey` | `string` | ✅ | — | AES encryption key from Infoflow enterprise console |
+| `apiHost` | `string` | ✅ | — | Infoflow API host, e.g. `https://api.im.baidu.com` |
+| `checkToken` | `string` | — | — | Message verification token from Infoflow enterprise console (**required for webhook mode**) |
+| `encodingAESKey` | `string` | — | — | AES encryption key from Infoflow enterprise console (**required for webhook mode**) |
 | `appKey` | `string` | ✅ | — | App Key from Infoflow enterprise console |
 | `appSecret` | `string` | ✅ | — | App Secret from Infoflow enterprise console |
 | `appAgentId` | `number` | — | — | App Agent ID (numeric); required for private message recall |
-| `robotName` | `string` | — | — | Bot display name in groups, used for @mention detection |
+| `robotName` | `string` | — | — | Bot display name in groups, used for @mention detection. **Without this, `mention-only` / `mention-and-watch` modes fall back to triggering on every message** |
 | `connectionMode` | `string` | — | `"webhook"` | `"webhook"` (Infoflow pushes to your server) or `"websocket"` (plugin connects to Infoflow) |
-| `wsGateway` | `string` | — | `"infoflow-open-gateway.weiyun.baidu.com"` | WebSocket gateway hostname, only used in `websocket` mode |
+| `wsGateway` | `string` | — | `"infoflow-open-gateway.baidu.com"` | WebSocket gateway hostname, only used in `websocket` mode |
 | `enabled` | `boolean` | — | `true` | Whether to enable the plugin |
 
 #### Access Control
@@ -821,6 +883,7 @@ https://your-domain/webhook/infoflow
 |-------|------|:--------:|---------|-------------|
 | `dmMessageFormat` | `string` | — | `"text"` | Format for private (DM) messages: `"text"` (plain) or `"markdown"` (rich text) |
 | `groupMessageFormat` | `string` | — | `"text"` | Format for group messages: `"text"` (plain) or `"markdown"` (rich text). **Note: `markdown` does not support quote replies** |
+| `textChunkLimit` | `number` | — | `1800` | Max characters per outbound message chunk; long messages are split into multiple messages |
 | `processingHint` | `boolean` | — | `true` | Send "⏳ processing..." hint when LLM is slow; send error message on failure |
 | `processingHintDelay` | `number` | — | `5` | Seconds to wait before sending the hint; set to `0` to send immediately |
 
@@ -878,6 +941,34 @@ tail -f ~/.openclaw/logs/gateway.log | grep -i infoflow
 
 ---
 
+<a id="built-in-commands"></a>
+
+## Built-in Commands
+
+### /infoflow-doctor — Self-check
+
+Diagnose configuration and API connectivity issues.
+
+```
+/infoflow-doctor
+```
+
+Checks: account config completeness, access token fetch, DM send test, group send test, image send test.
+
+### /infoflow-logs — Log viewer
+
+View recent Infoflow send/receive logs.
+
+```
+/infoflow-logs          # last 50 entries
+/infoflow-logs 100      # last 100 entries (max 200)
+/infoflow-logs 50-100   # page back: skip last 50, show previous 50
+```
+
+Log source: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. Total output capped at 20,000 characters.
+
+---
+
 <a id="extending-agent-tools"></a>
 
 ## Extending: Agent Tools
@@ -965,8 +1056,9 @@ Declare the skill path in `openclaw.plugin.json`:
 
 1. Check `replyMode` — confirm the group is allowed to trigger
 2. Check logs for incoming webhook requests
-3. Verify `robotName` matches the bot's display name (affects @ detection)
+3. Verify `robotName` matches the bot's display name in Infoflow (affects @mention detection). **Note: without `robotName`, `mention-only` / `mention-and-watch` modes fall back to triggering on every message**
 4. Check `groupPolicy` allows the group
+5. Send `/infoflow-doctor` in Infoflow to run self-checks
 
 ### Message recall failing?
 

package/docs/dev-guide.md

@@ -150,22 +150,22 @@ message-store 清理已撤回记录
 
 配置路径：`channels.infoflow` 或 `channels.infoflow.accounts.<id>`
 
-### 4.1 基础鉴权参数（必填）
+### 4.1 基础鉴权参数
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `checkToken` | string | Webhook 验证 Token（如流企业后台配置） |
-| `encodingAESKey` | string | 消息加密 AES Key（43 位 Base64） |
-| `appKey` | string | 应用 AppKey |
-| `appSecret` | string | 应用 AppSecret |
-| `apiHost` | string | 如流 API 域名，默认 `https://im.baidu.com` |
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `appKey` | string | 是 | 应用 AppKey |
+| `appSecret` | string | 是 | 应用 AppSecret |
+| `checkToken` | string | webhook 模式必填 | Webhook 验证 Token（如流企业后台配置） |
+| `encodingAESKey` | string | webhook 模式必填 | 消息加密 AES Key（43 位 Base64） |
+| `apiHost` | string | 否 | 如流 API 域名，默认 `https://api.im.baidu.com` |
 
 ### 4.2 连接方式
 
 | 参数 | 类型 | 默认 | 说明 |
 |------|------|------|------|
-| `connectionMode` | `"webhook"` \| `"websocket"` | `"webhook"` | 接入方式 |
-| `wsGateway` | string | - | WebSocket Gateway 域名（仅 websocket 模式） |
+| `connectionMode` | `"webhook"` \| `"websocket"` | `"websocket"` | 接入方式；websocket 只需 appKey+appSecret，推荐默认使用 |
+| `wsGateway` | string | - | WebSocket Gateway 域名（仅 websocket 模式，通常不需配置） |
 
 ### 4.3 私聊策略（dmPolicy）
 
@@ -175,13 +175,9 @@ message-store 清理已撤回记录
 | `"pairing"` | 配对模式，由框架处理（插件仅记录日志） |
 | `"allowlist"` | 仅 `allowFrom` 列表内的 uuapName 可触发 |
 
-```yaml
-channels:
-  infoflow:
-    dmPolicy: allowlist
-    allowFrom:
-      - zhangsan
-      - lisi
+```bash
+openclaw config set channels.infoflow.dmPolicy "allowlist"
+openclaw config set channels.infoflow.allowFrom '["zhangsan","lisi"]'
 ```
 
 ### 4.4 群聊策略（groupPolicy）
@@ -192,13 +188,9 @@ channels:
 | `"disabled"` | 所有群消息忽略 |
 | `"allowlist"` | 仅 `groupAllowFrom` 内的 groupId 可触发 |
 
-```yaml
-channels:
-  infoflow:
-    groupPolicy: allowlist
-    groupAllowFrom:
-      - "12345678"
-      - "87654321"
+```bash
+openclaw config set channels.infoflow.groupPolicy "allowlist"
+openclaw config set channels.infoflow.groupAllowFrom '["12345678","87654321"]'
 ```
 
 ### 4.5 群聊触发模式（replyMode）
@@ -213,33 +205,43 @@ channels:
 
 可在 account 级别配置，也可在 `groups.<groupId>` 级别覆盖：
 
-```yaml
-channels:
-  infoflow:
-    replyMode: mention-only
-    robotName: "小助手"
-    followUp: true
-    followUpWindow: 300       # 秒，默认 5 分钟
-    watchMentions:
-      - xuejian
-      - zhangsan
-    watchRegex: "上线|发布|故障"
-    groups:
-      "12345678":
-        replyMode: proactive   # 该群单独配置为 proactive
-        systemPrompt: "你是该群的专属助手，聚焦代码 review 相关问题"
+```bash
+# account 级别
+openclaw config set channels.infoflow.replyMode "mention-only"
+openclaw config set channels.infoflow.followUp true
+openclaw config set channels.infoflow.followUpWindow 300
+openclaw config set channels.infoflow.watchMentions '["xuejian","zhangsan"]'
+openclaw config set channels.infoflow.watchRegex "上线|发布|故障"
+```
+
+per-group 配置需直接编辑 `~/.openclaw/openclaw.json`（`openclaw config file` 查看路径）：
+
+```json
+{
+  "channels": {
+    "infoflow": {
+      "groups": {
+        "12345678": {
+          "replyMode": "proactive",
+          "systemPrompt": "你是该群的专属助手，聚焦代码 review 相关问题"
+        }
+      }
+    }
+  }
+}
 ```
 
 ### 4.6 其他配置
 
 | 参数 | 类型 | 默认 | 说明 |
 |------|------|------|------|
-| `robotName` | string | - | 机器人名称，用于识别 @机器人 |
+| `robotName` | string | - | 机器人名称（可选，@mention 检测已不依赖此字段） |
 | `processingHint` | boolean | `true` | LLM 超时后发送 "⏳ 处理中..." 提示 |
 | `processingHintDelay` | number | `5` | 提示延迟秒数 |
-| `dmMessageFormat` | `"text"` \| `"markdown"` | `"text"` | 私聊消息格式 |
-| `groupMessageFormat` | `"text"` \| `"markdown"` | `"text"` | 群聊消息格式（markdown 不支持 reply-to） |
+| `dmMessageFormat` | `"text"` \| `"markdown"` | `"markdown"` | 私聊消息格式 |
+| `groupMessageFormat` | `"text"` \| `"markdown"` | `"markdown"` | 群聊消息格式（markdown 不支持 reply-to） |
 | `appAgentId` | number | - | 应用 AgentId（私聊消息撤回依赖此字段） |
+| `textChunkLimit` | number | `1800` | 每条消息最大字符数，超长自动分片 |
 
 ---
 
@@ -507,17 +509,18 @@ vi.mock("../../src/channel/outbound.js", () => ({
 # 1. 安装依赖
 npm install
 
-# 2. 同步到 openclaw extensions 目录
-rsync -av --delete . ~/.openclaw/extensions/infoflow/ \
-  --exclude node_modules --exclude dist --exclude .git
+# 2. 部署到 openclaw（rsync + 重启 gateway，一键完成）
+./scripts/deploy.sh
 
-# 3. 重启 openclaw gateway（热加载）
-pkill -f "openclaw" && nohup openclaw gateway > /tmp/openclaw.log 2>&1 &
+# 3. 查看实时日志
+tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
 
-# 4. 查看实时日志
-tail -f /tmp/openclaw.log
+# 4. 如只需重启 gateway（不重新同步文件）
+openclaw gateway restart
 ```
 
+> `deploy.sh` 内部会 rsync 到 `~/.openclaw/extensions/infoflow-openclaw-plugin/` 并自动重启 gateway。
+
 ### 10.2 静态检查
 
 项目无 `tsc` 可执行文件，使用 Python 脚本验证 import 路径：
@@ -601,7 +604,17 @@ import { sendInfoflowMessage } from "../channel/outbound";
 
 ### 11.6 WebSocket 模式
 
-设置 `connectionMode: "websocket"` 时需额外配置 `wsGateway` 域名。WebSocket 模式由 `adapter/inbound/ws-receiver.ts` 处理，与 Webhook 模式共享 `webhook-parser.ts` 的消息分发和 dedup 逻辑。
+WebSocket 是推荐的接入方式，只需配置 `appKey` 和 `appSecret`，无需 Token 和 AESKey：
+
+```bash
+openclaw config set channels.infoflow.connectionMode "websocket"
+```
+
+WebSocket 模式由 `adapter/inbound/ws-receiver.ts` 处理，SDK 通过 `eventtype` 字段区分消息类型：
+- `MESSAGE_RECEIVE`：@机器人 的消息（`wasMentioned = true`）
+- `ALL_MESSAGE_FORWARD`：群内全量消息（需在如流后台开启全量订阅）
+
+两种模式共享 `webhook-parser.ts` 的消息分发和 dedup 逻辑。
 
 ### 11.7 新增配置字段