@dingxiang-me/openclaw-wechat 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-03-14
+
+### Added
+- 新增 `dm.mode=pairing`，首次私聊可接入 OpenClaw 原生配对审批流，不再只能依赖静态 `allowFrom`
+- 新增 WeCom 渠道 pairing metadata，支持 `quickstartAllowFrom`、`wecomUserId` 归一化以及审批通过后的默认通知回执
+- `wecom:selfcheck`、`wecom:agent:selfcheck`、`wecom:bot:selfcheck` 新增接入摘要，直接输出 `readiness` 与 `routing`
+
+### Changed
+- WeCom 渠道 metadata 补齐 `detailLabel`、`systemImage` 与 quickstart 提示，接入路径更贴近 OpenClaw 原生渠道
+- `/status` 输出优先展示“收消息 / 回消息 / 主动发送 / 媒体 / 语音 / 文档”准备情况，并显式展示 `bindings` / `dynamicAgent` 路由来源
+- WeCom Bot 长连接正常连接日志默认降到 `debug`，减少 `connect/opened/subscribed` 噪音
+- README（中英文）改成 `2.1.0` 接入口径，补充 `pairing`、selfcheck 摘要和推荐接入顺序
+
 ## [2.0.1] - 2026-03-14
 
 ### Fixed

package/README.en.md

@@ -10,7 +10,7 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 
 ## Table of Contents
 
-- [Major Update (v2.0.0)](#major-update-v200)
+- [Onboarding Update (v2.1.0)](#onboarding-update-v210)
 - [Highlights](#highlights)
 - [Mode Comparison](#mode-comparison)
 - [5-Minute Quick Start](#5-minute-quick-start)
@@ -28,41 +28,27 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 - [Development](#development)
 - [FAQ](#faq)
 
-## Major Update (v2.0.0)
+## Onboarding Update (v2.1.0)
 
-This is a real capability update, not a minor patch.  
-`OpenClaw-Wechat` now has **working WeCom Bot long-connection support** in real gateway runtime.
+This release focuses on setup quality, not feature sprawl. The goal is to make `OpenClaw-Wechat` behave more like a native OpenClaw channel during install and first-run.
 
-### WeCom Bot long connection
+### What changed
 
 | Item | Result |
 |---|---|
-| Official endpoint | `wss://openws.work.weixin.qq.com` |
-| Inbound commands | `aibot_msg_callback` / `aibot_event_callback` |
-| Outbound command | `aibot_respond_msg` |
-| Runtime | switched to `ws`, no longer blocked by built-in Node WebSocket `1006` failures |
-| Public Bot callback required | no, not in long-connection mode |
-| Verification command | `npm run wecom:bot:longconn:probe -- --json` |
-
-### Control UI and operations
-
-This release also keeps the earlier operations improvements: **WeCom supports visual configuration in Control UI**, so you no longer need to rely on manual JSON edits only.
-
-### Visual config in Control UI
-
-| Item | Status | Notes |
-|---|---|---|
-| WeCom config form | ✅ | `channels.wecom` can be edited/saved directly from UI |
-| Localized labels | ✅ | Common fields are now clearly labeled in Chinese for ops teams |
-| Sensitive-field hints | ✅ | secret/token/aesKey fields are marked as sensitive |
-| Runtime status clarity | ✅ | `Connected` is no longer stuck at `n/a`; default account display name is localized |
-| Inbound activity tracking | ✅ | `Last inbound` is updated after webhook callbacks (`n/a` before first inbound after restart is expected) |
+| DM pairing approval | Added `dm.mode=pairing`, backed by OpenClaw native pairing flow |
+| Quickstart metadata | Added `detailLabel`, `systemImage`, and `quickstartAllowFrom` |
+| `/status` readability | Status now leads with `receive / reply / send / media / voice / doc` readiness |
+| Selfcheck summaries | `wecom:selfcheck`, `wecom:agent:selfcheck`, and `wecom:bot:selfcheck` now print `readiness` and `routing` summaries |
+| Route visibility | Status and selfcheck now show whether routing comes from `bindings` or `dynamicAgent` |
+| Long-connection log noise | Normal connect / opened / subscribed logs moved to `debug` |
 
 ### Practical impact
 
-- Configure WeCom directly in `Channels -> WeCom` without hand-editing large config files.
-- Better readability for day-to-day ops and handover.
-- More accurate runtime status display reduces false alarm on “plugin not working”.
+- New users can start from the smallest working config, then add multi-account or dynamic routing later.
+- Teams that want controlled DM access can now use `pairing` instead of maintaining `allowFrom` only.
+- `/status` and selfcheck answer “can it receive, reply, and send?” before lower-level transport details.
+- Bot long-connection is quieter by default while still keeping useful warnings and errors.
 
 ## Highlights
 
@@ -75,7 +61,7 @@ This release also keeps the earlier operations improvements: **WeCom supports vi
 | Bot card replies | ✅ | `markdown/template_card` with automatic text fallback |
 | Multi-account support | ✅ | `channels.wecom.accounts.<id>` |
 | Sender allowlist and admin bypass | ✅ | `allowFrom` + `adminUsers` |
-| Direct-message policy | ✅ | `dm.mode=open/allowlist/deny` + account overrides |
+| Direct-message policy | ✅ | `dm.mode=open/allowlist/pairing/deny` + account overrides |
 | Event welcome reply (`enter_agent`) | ✅ | configurable via `events.enterAgentWelcome*` |
 | Command allowlist | ✅ | `/help`, `/status`, `/clear`, `/new`, etc. |
 | Group trigger policy | ✅ | mention-required or direct-trigger |
@@ -103,7 +89,7 @@ This release also keeps the earlier operations improvements: **WeCom supports vi
 openclaw plugins install @dingxiang-me/openclaw-wechat
 ```
 
-Recommended minimum package version: `2.0.0`. If `plugins.installs.openclaw-wechat` in `openclaw.json` still reports `1.7.x`, upgrade or reinstall first; those older npm packages do not expose the current WeCom channel metadata.
+Recommended minimum package version: `2.1.0`. If `plugins.installs.openclaw-wechat` in `openclaw.json` still reports `1.7.x`, upgrade or reinstall first; those older npm packages do not expose the current WeCom channel metadata.
 
 For local development or direct source-path loading, use:
 
@@ -159,6 +145,20 @@ If you are loading from source path instead, use the version below with `load.pa
 
 > Agent-mode note (important): configure **Trusted IP** in the WeCom self-built app settings and include the real egress IP of your OpenClaw gateway. Otherwise you may see "messages received but no reply".
 
+If you want first-contact DM approval, add:
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dm": {
+        "mode": "pairing"
+      }
+    }
+  }
+}
+```
+
 ### 4) Restart and verify
 
 ```bash
@@ -169,6 +169,11 @@ npm run wecom:agent:selfcheck -- --all-accounts
 npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
+Selfcheck now starts with two summary lines:
+
+- `readiness`: whether receive / reply / send are currently usable
+- `routing`: whether `bindings` and `dynamicAgent` are active
+
 ## Requirements
 
 | Item | Description |
@@ -310,7 +315,7 @@ When multi-account is enabled, each account can override Bot callback credential
 | Sender ACL | `allowFrom`, `allowFromRejectMessage` |
 | Command ACL | `commands.enabled`, `commands.allowlist`, `commands.rejectMessage` |
 | Admin bypass | `adminUsers` |
-| Direct-message policy | `dm.mode`, `dm.allowFrom`, `dm.rejectMessage` |
+| Direct-message policy | `dm.mode`, `dm.allowFrom`, `dm.rejectMessage` (`open / allowlist / pairing / deny`) |
 | Event policy | `events.enabled`, `events.enterAgentWelcomeEnabled`, `events.enterAgentWelcomeText` |
 | Group trigger | `groupChat.enabled`, `groupChat.triggerMode`, `groupChat.mentionPatterns`, `groupChat.triggerKeywords` |
 | Dynamic route | `dynamicAgent.*` (compatible with `dynamicAgents.*`, `dm.createAgentOnFirstMessage`) |
@@ -433,7 +438,7 @@ Outbound target formats:
 |---|---|
 | `WECOM_ALLOW_FROM*` | sender authorization |
 | `WECOM_COMMANDS_*` | command ACL |
-| `WECOM_DM_*`, `WECOM_<ACCOUNT>_DM_*` | DM policy + allowlist |
+| `WECOM_DM_*`, `WECOM_<ACCOUNT>_DM_*` | DM policy + allowlist / pairing controls |
 | `WECOM_EVENTS_*`, `WECOM_<ACCOUNT>_EVENTS_*` | event handling + enter_agent welcome text |
 | `WECOM_GROUP_CHAT_*` | group trigger policy |
 | `WECOM_DEBOUNCE_*` | text debounce |

package/README.md

@@ -12,7 +12,7 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 
 ## 目录
 
-- [重大更新（v2.0.0）](#重大更新v200)
+- [接入更新（v2.1.0）](#接入更新v210)
 - [功能概览](#功能概览)
 - [模式对比](#模式对比)
 - [5 分钟极速上手](#5-分钟极速上手)
@@ -33,75 +33,42 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 - [FAQ](#faq)
 - [版本与贡献](#版本与贡献)
 
-## 重大更新（v2.0.0）
+## 接入更新（v2.1.0）
 
-这次是一次真正的能力级更新，不是小修补。  
-`OpenClaw-Wechat` 现在已经把 **企业微信智能机器人长连接** 正式做成可用能力，并且已经在真实网关环境下完成：
+这版不是继续堆新平台能力，而是把接入体验收口到“更像 OpenClaw 原生渠道”的状态。
 
-- WebSocket 握手成功
-- `aibot_subscribe` 鉴权成功
-- 心跳 `ping` / 回执成功
-- 网关日志出现 `socket opened` 和 `subscribed`
-
-### 企业微信 Bot 长连接已正式可用
+### 这版新增了什么
 
 | 项目 | 结果 |
 |---|---|
-| 官方地址 | `wss://openws.work.weixin.qq.com` |
-| 入站命令 | `aibot_msg_callback` / `aibot_event_callback` |
-| 出站命令 | `aibot_respond_msg` |
-| 运行时实现 | 已切换为 `ws`，不再使用会导致 `1006` 的 Node 内置 WebSocket |
-| Bot 回调公网依赖 | 长连接模式下不需要 |
-| 自检命令 | `npm run wecom:bot:longconn:probe -- --json` |
-
-这次版本同时还保留并增强了原有的 **WeCom Doc 工具链**。  
-现在 `OpenClaw-Wechat` 已经同时具备：
-
-- 后台可视化配置
-- WeCom Doc 文档/表格/收集表工具
-- 文档权限与协作者管理
-- 分享链接可用性诊断
-- 文档权限打不开问题的直接诊断
-- 链接文本输出完整性修复（URL 下划线不再丢失）
-
-### 这次版本解决了什么
-
-| 场景 | 旧问题 | 现在的处理方式 |
-|---|---|---|
-| 企业微信 Bot 长连接 | 旧版地址、命令字和运行时实现不对，连接阶段直接 `1006` | 已对齐官方地址、协议命令和 `ws` 实现，真实网关已订阅成功 |
-| 想验证“到底连上没有” | 只能看零散日志，难以区分握手、鉴权还是心跳失败 | `wecom:bot:longconn:probe` 会直接验证握手、鉴权与心跳 |
-| 创建文档后自己打不开 | 文档创建成功，但发起人没被自动授权 | `create` 默认自动把当前企微请求人加入协作者 |
-| 分享链接能发出来，但别人打开像“文档不存在” | 无法快速判断是权限、分享码还是 guest 访问问题 | `validate_share_link` 直接诊断 `guest / blankpage / scode / 路径资源 ID` |
-| 只知道“更新成员权限成功”，但还是打不开 | 成员权限、查看规则、外部分享是三套概念，容易混淆 | `diagnose_auth` 直接输出企业内/企业外访问、查看成员、协作者与请求人角色 |
-| 把分享链接路径当成 `docId` 使用 | 后续 API 调用报 `invalid docid` | `create/share/get_auth` 结果显式返回真实 `docId`，并给出使用提示 |
-| 链接里有下划线，发出去后被改坏 | Markdown 清洗误伤 URL | 文本格式化已修复，URL 下划线完整保留 |
-
-### 可视化配置能力（Control UI）
-
-| 项目 | 现状 | 说明 |
-|---|---|---|
-| WeCom 配置表单 | ✅ | `channels.wecom` 支持在后台页面直接编辑与保存 |
-| 中文字段标签 | ✅ | 常用字段（如 `corpId`、`callbackToken`、`accounts.*`）均已中文化 |
-| 敏感项标记 | ✅ | `secret/token/aesKey` 字段按敏感项展示 |
-| 状态展示 | ✅ | `Connected` 不再长期 `n/a`，默认账号显示名中文化为“默认账号” |
-| 入站状态追踪 | ✅ | 收到回调后自动更新 `Last inbound`（重启后首次入站前为 `n/a` 属正常） |
-| 文档工具开关 | ✅ | `tools.doc` 等文档相关配置可被 schema 正确识别 |
-
-### 文档工具升级摘要
-
-| 能力层 | 新增内容 |
-|---|---|
-| 文档基础 | `create`、`rename`、`get_info`、`share`、`delete` |
-| 权限管理 | `grant_access`、`add_collaborators`、`set_join_rule`、`set_member_auth`、`set_safety_setting` |
-| 运维诊断 | `get_auth`、`diagnose_auth`、`validate_share_link` |
-| 表格/收集表 | `get_sheet_properties`、`create_collect`、`modify_collect`、`get_form_info`、`get_form_answer`、`get_form_statistic` |
-
-### 你升级后能直接获得的变化
-
-- 在 OpenClaw 后台的 `Channels -> WeCom` 页面可直接配置并保存核心参数。
-- 在同一个插件里直接调用 `wecom_doc`，不需要额外安装第二个 WeCom Doc 插件。
-- 现在排查“为什么这个链接打不开”不需要再手翻日志和原始 JSON，工具会直接给出结论。
-- 文档创建、协作者授权、分享链接诊断已经形成闭环，适合直接上线给真实企微用户使用。
+| 私聊配对审批 | 新增 `dm.mode=pairing`，首次私聊会生成 OpenClaw 原生配对审批 |
+| Quickstart 元信息 | 渠道 metadata 补齐 `detailLabel`、`systemImage`、`quickstartAllowFrom` |
+| `/status` 可读性 | 优先展示 `收消息 / 回消息 / 主动发送 / 媒体 / 语音 / 文档` 准备情况 |
+| Selfcheck 摘要 | `wecom:selfcheck` / `wecom:agent:selfcheck` / `wecom:bot:selfcheck` 新增 `readiness` 与 `routing` 摘要 |
+| 路由可见性 | 明确显示当前是否命中 `bindings` 或 `dynamicAgent` |
+| 长连接日志降噪 | 正常的 connect / opened / subscribed 改为 `debug`，减少默认噪音 |
+
+### 这版对接入有什么实际影响
+
+- 新用户现在可以按最小配置先跑通，再决定是否启用多账号、动态路由和文档工具。
+- 需要私聊审批时，不再只能靠手写 `allowFrom`，可以直接用 `pairing` 模式接到 OpenClaw 审批流。
+- `/status` 和 selfcheck 先回答“能不能收、能不能回、能不能发”，再展开工程细节。
+- Bot 长连接默认日志更安静，排障时再开 `debug` 看正常心跳和订阅细节。
+
+### 当前推荐的接入顺序
+
+1. 先选一个主入口：
+   - Bot 长连接：适合最快跑通对话
+   - Agent：适合需要主动发送、菜单、自建应用能力
+2. 再决定私聊准入：
+   - `open`：直接可聊
+   - `allowlist`：仅显式白名单
+   - `pairing`：首次私聊先审批
+3. 最后再加增强项：
+   - `bindings`
+   - `dynamicAgent`
+   - `wecom_doc`
+   - 本地语音转写
 
 ## 5 分钟极速上手
 
@@ -113,7 +80,7 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 openclaw plugins install @dingxiang-me/openclaw-wechat
 ```
 
-> 最低建议版本：`2.0.0`。如果 `openclaw.json` 里的 `plugins.installs.openclaw-wechat` 仍显示 `1.7.x`，请先升级或重装；旧包不会正确注册 `wecom` channel 元数据。
+> 最低建议版本：`2.1.0`。如果 `openclaw.json` 里的 `plugins.installs.openclaw-wechat` 仍显示 `1.7.x`，请先升级或重装；旧包不会正确注册 `wecom` channel 元数据。
 
 如果你是在本地开发或要直接跑仓库源码，再用下面这套：
 
@@ -170,6 +137,20 @@ npm install
 
 > Agent 模式补充（重要）：在企业微信自建应用后台请配置**可信 IP**，把 OpenClaw 网关实际出网 IP 加入白名单。否则可能出现“能收到消息但不回复”。
 
+如果你希望私聊先审批，再开放会话，可以直接加：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dm": {
+        "mode": "pairing"
+      }
+    }
+  }
+}
+```
+
 ### Step 4. 重启并自检
 
 ```bash
@@ -180,6 +161,11 @@ npm run wecom:agent:selfcheck -- --all-accounts
 npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
+现在自检输出会先给出两行摘要：
+
+- `readiness`: 当前是否能收、能回、能发
+- `routing`: 当前是否启用 `bindings` 和 `dynamicAgent`
+
 ### Step 5. 发一条消息验证
 
 | 验证项 | 预期结果 |
@@ -201,7 +187,7 @@ npm run wecom:bot:selfcheck -- --all-accounts
 | Bot 卡片回包 | ✅ | 支持 `markdown/template_card`，失败自动降级文本 |
 | 多账户 | ✅ | `channels.wecom.accounts.<id>` |
 | 发送者授权控制 | ✅ | `allowFrom` + 账户级覆盖 |
-| 私聊策略（DM） | ✅ | `dm.mode=open/allowlist/deny` + 账户级覆盖 |
+| 私聊策略（DM） | ✅ | `dm.mode=open/allowlist/pairing/deny` + 账户级覆盖 |
 | 事件欢迎语（enter_agent） | ✅ | `events.enterAgentWelcome*` 可配置 |
 | 命令白名单 | ✅ | `/help` `/status` `/clear` `/new` 等 |
 | 群聊触发策略 | ✅ | 支持 `direct/mention/keyword` 三种模式 |
@@ -662,7 +648,7 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | 拒绝文案 | `allowFromRejectMessage` | 未授权提示 |
 | 管理员 | `adminUsers` | 绕过命令白名单 |
 | 命令白名单 | `commands.enabled` + `commands.allowlist` | 限制 `/` 指令 |
-| 私聊策略 | `dm.mode` + `dm.allowFrom` + `dm.rejectMessage` | 控制私聊开放/白名单/拒绝 |
+| 私聊策略 | `dm.mode` + `dm.allowFrom` + `dm.rejectMessage` | 控制私聊开放/白名单/配对审批/拒绝 |
 | 事件策略 | `events.enabled` + `events.enterAgentWelcomeEnabled` + `events.enterAgentWelcomeText` | 控制事件处理与 enter_agent 欢迎语 |
 | 群聊触发 | `groupChat.enabled` + `triggerMode` + `mentionPatterns` + `triggerKeywords` | 控制群消息触发条件（自建应用支持 `direct/mention/keyword`；Bot 模式按平台限制固定 `mention`） |
 | 动态路由 | `dynamicAgent.*`（兼容 `dynamicAgents.*`、`dm.createAgentOnFirstMessage`） | 动态 Agent + workspace bootstrap 播种 |

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-wechat",
   "name": "OpenClaw-Wechat",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "channels": [
     "wecom"
@@ -672,10 +672,11 @@
             "enum": [
               "open",
               "allowlist",
+              "pairing",
               "deny"
             ],
             "default": "open",
-            "description": "私聊策略：open=开放，allowlist=白名单，deny=关闭"
+            "description": "私聊策略：open=开放，allowlist=白名单，pairing=首次私聊需审批，deny=关闭"
           },
           "rejectMessage": {
             "type": "string",
@@ -688,7 +689,7 @@
           },
           "allowFrom": {
             "type": "array",
-            "description": "私聊白名单（mode=allowlist 时生效）",
+            "description": "私聊白名单（mode=allowlist/pairing 时作为显式放行名单）",
             "items": {
               "type": "string",
               "minLength": 1
@@ -1194,14 +1195,15 @@
                   "enum": [
                     "open",
                     "allowlist",
+                    "pairing",
                     "deny"
                   ],
                   "default": "open",
-                  "description": "私聊策略：open=开放，allowlist=白名单，deny=关闭"
+                  "description": "私聊策略：open=开放，allowlist=白名单，pairing=首次私聊需审批，deny=关闭"
                 },
                 "allowFrom": {
                   "type": "array",
-                  "description": "私聊白名单（mode=allowlist 时生效）",
+                  "description": "私聊白名单（mode=allowlist/pairing 时作为显式放行名单）",
                   "items": {
                     "type": "string",
                     "minLength": 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingxiang-me/openclaw-wechat",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "type": "module",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "license": "MIT",
@@ -24,10 +24,13 @@
       "id": "wecom",
       "label": "企业微信 WeCom",
       "selectionLabel": "企业微信 WeCom（自建应用/Bot）",
+      "detailLabel": "企业微信自建应用 / Bot",
       "docsPath": "/channels/wecom",
       "docsLabel": "wecom",
       "blurb": "企业微信消息通道（自建应用回调 + Bot 回调 + 发送 API）。",
       "order": 80,
+      "systemImage": "building.2.crop.circle",
+      "quickstartAllowFrom": true,
       "aliases": [
         "wework",
         "qiwei",

package/src/core.js

@@ -55,7 +55,7 @@ const BOT_CARD_MODE_SET = new Set(["markdown", "template_card"]);
 const DELIVERY_FALLBACK_LAYER_SET = new Set(DEFAULT_DELIVERY_FALLBACK_ORDER);
 const DYNAMIC_AGENT_MAP_SPLITTER = /[,\n]/;
 const GROUP_CHAT_TRIGGER_MODE_SET = new Set(["direct", "mention", "keyword"]);
-const DM_POLICY_MODE_SET = new Set(["open", "allowlist", "deny"]);
+const DM_POLICY_MODE_SET = new Set(["open", "allowlist", "pairing", "deny"]);
 const DYNAMIC_AGENT_MODE_SET = new Set(["mapping", "deterministic", "hybrid"]);
 const DYNAMIC_AGENT_ID_STRATEGY_SET = new Set(["readable-hash"]);
 const LEGACY_INLINE_ACCOUNT_RESERVED_KEYS = new Set([
@@ -582,6 +582,7 @@ function normalizeWecomDmPolicyMode(value, fallback = "open") {
     .toLowerCase();
   if (!normalized) return fallback;
   if (normalized === "closed" || normalized === "close") return "deny";
+  if (normalized === "disabled") return "deny";
   if (normalized === "whitelist") return "allowlist";
   if (DM_POLICY_MODE_SET.has(normalized)) return normalized;
   return fallback;
@@ -836,9 +837,16 @@ export function resolveWecomDmPolicyConfig({
     channelDmConfig.rejectMessage,
     channelDmConfig.blockMessage,
     readDmRejectMessageEnv(envVars, processEnv, accountId),
-    mode === "deny" ? "当前渠道私聊已关闭，请联系管理员。" : "当前私聊账号未授权，请联系管理员。",
-  );
-  const effectiveMode = mode === "allowlist" && allowFrom.length === 0 ? "deny" : mode;
+    mode === "deny"
+      ? "当前渠道私聊已关闭，请联系管理员。"
+      : mode === "pairing"
+        ? "当前私聊需先完成配对审批。"
+        : "当前私聊账号未授权，请联系管理员。",
+  );
+  const effectiveMode =
+    mode === "allowlist" && allowFrom.length === 0
+      ? "deny"
+      : mode;
   return {
     mode: effectiveMode,
     allowFrom,

package/src/wecom/agent-inbound-guards.js

@@ -1,3 +1,8 @@
+import {
+  issueWecomPairingChallenge,
+  resolveWecomDirectMessageAccess,
+} from "./pairing.js";
+
 function assertFunction(name, value) {
   if (typeof value !== "function") {
     throw new Error(`agent-inbound-guards: ${name} is required`);
@@ -61,28 +66,46 @@ export async function applyWecomAgentInboundGuards({
 
   const commandPolicy = resolveWecomCommandPolicy(api);
   const isAdminUser = commandPolicy.adminUsers.includes(normalizedFromUser);
-  const dmPolicy = resolveWecomDmPolicy(api, config?.accountId || accountId || "default", config);
+  const resolvedAccountId = config?.accountId || accountId || "default";
+  const dmPolicy = resolveWecomDmPolicy(api, resolvedAccountId, config);
+  const allowFromPolicy = resolveWecomAllowFromPolicy(api, resolvedAccountId, config);
+
   if (!isGroupChat) {
-    if (dmPolicy.mode === "deny") {
-      await sendTextToUser(dmPolicy.rejectMessage || "当前渠道私聊已关闭，请联系管理员。");
-      return { ok: false, commandBody: nextCommandBody, isAdminUser };
-    }
-    if (dmPolicy.mode === "allowlist") {
-      const dmSenderAllowed = isAdminUser || isWecomSenderAllowed({
-        senderId: normalizedFromUser,
-        allowFrom: dmPolicy.allowFrom,
+    const dmAccess = await resolveWecomDirectMessageAccess({
+      api,
+      accountId: resolvedAccountId,
+      dmPolicy,
+      allowFromPolicy,
+      normalizedFromUser,
+      isAdminUser,
+      isWecomSenderAllowed,
+    });
+    if (dmAccess.decision === "pairing") {
+      const pairing = await issueWecomPairingChallenge({
+        api,
+        accountId: resolvedAccountId,
+        fromUser,
+        normalizedFromUser,
+        sendPairingReply: sendTextToUser,
       });
-      if (!dmSenderAllowed) {
-        await sendTextToUser(dmPolicy.rejectMessage || "当前私聊账号未授权，请联系管理员。");
-        return { ok: false, commandBody: nextCommandBody, isAdminUser };
+      if (!pairing.created && pairing.unsupported) {
+        await sendTextToUser(dmPolicy.rejectMessage || "当前私聊需先完成配对审批。");
       }
+      return { ok: false, commandBody: nextCommandBody, isAdminUser };
+    }
+    if (dmAccess.decision !== "allow") {
+      await sendTextToUser(dmAccess.rejectText || dmPolicy.rejectMessage || "当前私聊账号未授权，请联系管理员。");
+      return { ok: false, commandBody: nextCommandBody, isAdminUser };
     }
   }
-  const allowFromPolicy = resolveWecomAllowFromPolicy(api, config?.accountId || accountId || "default", config);
-  const senderAllowed = isAdminUser || isWecomSenderAllowed({
-    senderId: normalizedFromUser,
-    allowFrom: allowFromPolicy.allowFrom,
-  });
+
+  const senderAllowed =
+    isAdminUser ||
+    allowFromPolicy.allowFrom.includes("*") ||
+    isWecomSenderAllowed({
+      senderId: normalizedFromUser,
+      allowFrom: allowFromPolicy.allowFrom,
+    });
   if (!senderAllowed) {
     api?.logger?.warn?.(
       `wecom: sender blocked by allowFrom account=${config?.accountId || "default"} user=${normalizedFromUser}`,

package/src/wecom/bot-inbound-executor.js

@@ -125,7 +125,7 @@ export async function executeWecomBotInboundFlow(payload = {}) {
     }
     state.commandBody = groupGuardResult.commandBody;
 
-    const commandGuardResult = applyWecomBotCommandAndSenderGuard({
+    const commandGuardResult = await applyWecomBotCommandAndSenderGuard({
       api,
       accountId: state.accountId,
       fromUser,

package/src/wecom/bot-inbound-guards.js

@@ -1,3 +1,8 @@
+import {
+  issueWecomPairingChallenge,
+  resolveWecomDirectMessageAccess,
+} from "./pairing.js";
+
 function assertFunction(name, value) {
   if (typeof value !== "function") {
     throw new Error(`bot-inbound-guards: ${name} is required`);
@@ -50,7 +55,7 @@ export function applyWecomBotGroupChatGuard({
   };
 }
 
-export function applyWecomBotCommandAndSenderGuard({
+export async function applyWecomBotCommandAndSenderGuard({
   api,
   accountId = "default",
   fromUser,
@@ -77,37 +82,57 @@ export function applyWecomBotCommandAndSenderGuard({
   const commandPolicy = resolveWecomCommandPolicy(api);
   const isAdminUser = commandPolicy.adminUsers.includes(String(normalizedFromUser ?? "").trim().toLowerCase());
   const dmPolicy = resolveWecomDmPolicy(api, accountId, {});
+  const allowFromPolicy = resolveWecomAllowFromPolicy(api, accountId, {});
+
   if (!isGroupChat) {
-    if (dmPolicy.mode === "deny") {
+    const dmAccess = await resolveWecomDirectMessageAccess({
+      api,
+      accountId,
+      dmPolicy,
+      allowFromPolicy,
+      normalizedFromUser,
+      isAdminUser,
+      isWecomSenderAllowed,
+    });
+    if (dmAccess.decision === "pairing") {
+      const pairing = await issueWecomPairingChallenge({
+        api,
+        accountId,
+        fromUser,
+        normalizedFromUser,
+        sendPairingReply: async (text) => text,
+      });
       return {
         ok: false,
-        finishText: dmPolicy.rejectMessage || "当前渠道私聊已关闭，请联系管理员。",
+        finishText:
+          pairing.created
+            ? pairing.replyText || ""
+            : !pairing.unsupported
+              ? ""
+            : dmPolicy.rejectMessage || "当前私聊需先完成配对审批。",
         commandBody: String(commandBody ?? ""),
         isAdminUser,
         commandPolicy,
       };
     }
-    if (dmPolicy.mode === "allowlist") {
-      const dmSenderAllowed = isAdminUser || isWecomSenderAllowed({
-        senderId: normalizedFromUser,
-        allowFrom: dmPolicy.allowFrom,
-      });
-      if (!dmSenderAllowed) {
-        return {
-          ok: false,
-          finishText: dmPolicy.rejectMessage || "当前私聊账号未授权，请联系管理员。",
-          commandBody: String(commandBody ?? ""),
-          isAdminUser,
-          commandPolicy,
-        };
-      }
+    if (dmAccess.decision !== "allow") {
+      return {
+        ok: false,
+        finishText: dmAccess.rejectText || dmPolicy.rejectMessage || "当前私聊账号未授权，请联系管理员。",
+        commandBody: String(commandBody ?? ""),
+        isAdminUser,
+        commandPolicy,
+      };
     }
   }
-  const allowFromPolicy = resolveWecomAllowFromPolicy(api, accountId, {});
-  const senderAllowed = isAdminUser || isWecomSenderAllowed({
-    senderId: normalizedFromUser,
-    allowFrom: allowFromPolicy.allowFrom,
-  });
+
+  const senderAllowed =
+    isAdminUser ||
+    allowFromPolicy.allowFrom.includes("*") ||
+    isWecomSenderAllowed({
+      senderId: normalizedFromUser,
+      allowFrom: allowFromPolicy.allowFrom,
+    });
   if (!senderAllowed) {
     return {
       ok: false,

package/src/wecom/bot-long-connection-manager.js

@@ -260,7 +260,7 @@ export function createWecomBotLongConnectionManager({
     if (!agent) {
       agent = new wsProxyAgentCtor(proxyUrl);
       wsProxyAgentCache.set(proxyUrl, agent);
-      api?.logger?.info?.(
+      api?.logger?.debug?.(
         `wecom(bot-longconn): websocket proxy enabled account=${client.accountId} proxy=${printableProxy}`,
       );
     }
@@ -729,7 +729,7 @@ export function createWecomBotLongConnectionManager({
             transport: "bot.longConnection",
           });
           startPingLoop(client, api);
-          api?.logger?.info?.(`wecom(bot-longconn): subscribed account=${client.accountId}`);
+          api?.logger?.debug?.(`wecom(bot-longconn): subscribed account=${client.accountId}`);
         } else {
           api?.logger?.warn?.(
             `wecom(bot-longconn): subscribe failed account=${client.accountId} errcode=${errcode} errmsg=${errmsg}`,
@@ -799,7 +799,7 @@ export function createWecomBotLongConnectionManager({
         `wecom(bot-longconn): websocket proxy init failed account=${client.accountId}: ${String(err?.message || err)}`,
       );
     }
-    api?.logger?.info?.(
+    api?.logger?.debug?.(
       `wecom(bot-longconn): connect attempt account=${client.accountId} marker=${LONG_CONNECTION_RUNTIME_MARKER} url=${wsUrl} proxy=${proxyUrl || "direct"} wsCtor=${String(webSocketCtor?.name || "unknown")}`,
     );
     client.ws = new webSocketCtor(wsUrl, [], wsOptions);
@@ -822,7 +822,7 @@ export function createWecomBotLongConnectionManager({
             secret: client.config.longConnection.secret,
           },
         }) || "";
-      api?.logger?.info?.(`wecom(bot-longconn): socket opened account=${client.accountId} url=${wsUrl}`);
+      api?.logger?.debug?.(`wecom(bot-longconn): socket opened account=${client.accountId} url=${wsUrl}`);
     });
     bindSocketListener(client.ws, "message", (event) => {
       void handleSocketMessage(client, api, event);

package/src/wecom/channel-plugin.js

@@ -3,6 +3,7 @@ import {
   getWecomChannelInboundActivity,
   getWecomInboundActivity,
 } from "./channel-status-state.js";
+import { normalizeWecomAllowFromEntry } from "../core.js";
 
 function assertFunction(name, fn) {
   if (typeof fn !== "function") {
@@ -160,9 +161,30 @@ export function createWecomChannelPlugin({
       id: "wecom",
       label: "企业微信 WeCom",
       selectionLabel: "企业微信 WeCom（自建应用/Bot）",
+      detailLabel: "企业微信自建应用 / Bot",
       docsPath: "/channels/wecom",
       blurb: "企业微信消息通道（自建应用回调 + Bot 回调 + 发送 API）。",
       aliases: ["wework", "qiwei", "wxwork"],
+      systemImage: "building.2.crop.circle",
+      quickstartAllowFrom: true,
+    },
+    pairing: {
+      idLabel: "wecomUserId",
+      normalizeAllowEntry: (entry) => normalizeWecomAllowFromEntry(entry),
+      notifyApproval: async ({ cfg, id }) => {
+        const normalizedUserId = normalizeWecomAllowFromEntry(id);
+        if (!normalizedUserId) return;
+        const config = getWecomConfig({ config: cfg }, "default");
+        if (!config?.corpId || !config?.corpSecret || !config?.agentId) return;
+        await sendWecomText({
+          corpId: config.corpId,
+          corpSecret: config.corpSecret,
+          agentId: config.agentId,
+          toUser: normalizedUserId,
+          text: "OpenClaw: your access has been approved.",
+          proxyUrl: config.outboundProxy,
+        });
+      },
     },
     configSchema: {
       schema: wecomChannelConfigSchema,

package/src/wecom/command-handlers.js

@@ -98,6 +98,7 @@ export function createWecomCommandHandlers({
   async function handleStatusCommand({ api, fromUser, corpId, corpSecret, agentId, accountId, proxyUrl }) {
     const config = getWecomConfig(api, accountId);
     const accountIds = listWecomAccountIds(api);
+    const bindingsCount = Array.isArray(api?.config?.bindings) ? api.config.bindings.length : 0;
     const webhookTargetAliases = listWebhookTargetAliases(config);
     const voiceConfig = resolveWecomVoiceTranscriptionConfig(api);
     const voiceRuntimeInfo = await inspectWecomVoiceTranscriptionRuntime({ api, voiceConfig });
@@ -134,6 +135,7 @@ export function createWecomCommandHandlers({
       webhookBotPolicy,
       dynamicAgentPolicy,
       observabilityMetrics,
+      bindingsCount,
     });
 
     await sendWecomText({
@@ -150,6 +152,8 @@ export function createWecomCommandHandlers({
 
   function buildBotStatus(api, fromUser) {
     const allWebhookTargetAliases = listAllWebhookTargetAliases(api);
+    const config = getWecomConfig(api, "default");
+    const bindingsCount = Array.isArray(api?.config?.bindings) ? api.config.bindings.length : 0;
     const commandPolicy = resolveWecomCommandPolicy(api);
     const allowFromPolicy = resolveWecomAllowFromPolicy(api, "default", {});
     const dmPolicy = resolveWecomDmPolicy(api, "default", {});
@@ -176,6 +180,8 @@ export function createWecomCommandHandlers({
       webhookBotPolicy,
       dynamicAgentPolicy,
       observabilityMetrics,
+      config,
+      bindingsCount,
     });
   }
 

package/src/wecom/command-status-text.js

@@ -17,9 +17,29 @@ function buildDmPolicyStatusLine(dmPolicy = {}) {
     const count = Array.isArray(dmPolicy?.allowFrom) ? dmPolicy.allowFrom.length : 0;
     return `✅ 私聊策略：白名单（${count} 个用户）`;
   }
+  if (mode === "pairing") {
+    const count = Array.isArray(dmPolicy?.allowFrom) ? dmPolicy.allowFrom.length : 0;
+    return count > 0
+      ? `✅ 私聊策略：配对审批（pairing，显式放行 ${count} 个用户）`
+      : "✅ 私聊策略：配对审批（pairing，首次私聊需审批）";
+  }
   return "ℹ️ 私聊策略：开放（open）";
 }
 
+function buildRoutePolicyStatusLine({ bindingsCount = 0, dynamicAgentPolicy = {} } = {}) {
+  const count = Math.max(0, Number(bindingsCount) || 0);
+  if (count > 0 && dynamicAgentPolicy?.enabled) {
+    return `✅ 路由策略：OpenClaw bindings 优先（${count} 条），动态 Agent 补充（mode=${dynamicAgentPolicy.mode}）`;
+  }
+  if (count > 0) {
+    return `✅ 路由策略：OpenClaw bindings（${count} 条）`;
+  }
+  if (dynamicAgentPolicy?.enabled) {
+    return `✅ 路由策略：动态 Agent（mode=${dynamicAgentPolicy.mode}）`;
+  }
+  return "ℹ️ 路由策略：使用 OpenClaw 默认 Agent 路由";
+}
+
 function buildEventPolicyStatusLine(eventPolicy = {}) {
   if (eventPolicy?.enabled === false) {
     return "⚠️ 事件策略：已关闭";
@@ -80,6 +100,43 @@ function buildVoiceStatusLine(voiceConfig = {}, voiceRuntimeInfo = null) {
   return `${baseLine}（${commandState}，${ffmpegState}）${issueSuffix}`;
 }
 
+function buildAgentReadinessLines({ config = {}, voiceConfig = {} } = {}) {
+  const canReceive = Boolean(config?.callbackToken && config?.callbackAesKey && config?.webhookPath);
+  const canReply = Boolean(config?.corpId && config?.corpSecret && config?.agentId);
+  const docEnabled = config?.tools?.doc !== false;
+  const voiceEnabled = voiceConfig?.enabled === true;
+  return [
+    `${canReceive ? "✅" : "⚠️"} 收消息：${canReceive ? "Agent 回调已配置" : "缺少 callbackToken / callbackAesKey / webhookPath"}`,
+    `${canReply ? "✅" : "⚠️"} 回消息：${canReply ? "Agent API 可用" : "缺少 corpId / corpSecret / agentId"}`,
+    `${canReply ? "✅" : "⚠️"} 主动发送：${canReply ? "文本/图片/文件可主动发送" : "主动发送依赖 Agent API 配置"}`,
+    `${canReply ? "✅" : "⚠️"} 媒体链路：${canReply ? "图片/文件/语音回退链路可用" : "需先完成 Agent API 配置"}`,
+    `${voiceEnabled ? "✅" : "ℹ️"} 语音能力：${voiceEnabled ? "已启用本地转写回退" : "仅使用企业微信 Recognition"}`,
+    `${docEnabled ? "✅" : "ℹ️"} 文档工具：${docEnabled ? "wecom_doc 已启用" : "未启用"}`,
+  ];
+}
+
+function buildBotReadinessLines({ botConfig = {}, config = {} } = {}) {
+  const longConnectionEnabled =
+    botConfig?.longConnection?.enabled === true &&
+    Boolean(String(botConfig?.longConnection?.botId ?? "").trim()) &&
+    Boolean(String(botConfig?.longConnection?.secret ?? "").trim());
+  const webhookEnabled =
+    botConfig?.enabled === true &&
+    Boolean(String(botConfig?.token ?? "").trim()) &&
+    Boolean(String(botConfig?.encodingAesKey ?? "").trim()) &&
+    Boolean(String(botConfig?.webhookPath ?? "").trim());
+  const canReceive = longConnectionEnabled || webhookEnabled;
+  const canReply = canReceive;
+  const docEnabled = config?.tools?.doc !== false;
+  return [
+    `${canReceive ? "✅" : "⚠️"} 收消息：${canReceive ? (longConnectionEnabled ? "Bot 长连接/回调已配置" : "Bot webhook 已配置") : "缺少 Bot webhook 或长连接凭证"}`,
+    `${canReply ? "✅" : "⚠️"} 回消息：${canReply ? "原生 stream + fallback 可用" : "需先完成 Bot 配置"}`,
+    `${canReceive ? "ℹ️" : "⚠️"} 主动发送：${canReceive ? "Bot 以会话回包为主；跨会话主动发送建议配合 Agent/Webhook 目标" : "需先完成 Bot 配置"}`,
+    `${canReceive ? "✅" : "⚠️"} 媒体链路：${canReceive ? "Bot 图片/文件/PDF 入站理解已启用" : "需先完成 Bot 配置"}`,
+    `${docEnabled ? "✅" : "ℹ️"} 文档工具：${docEnabled ? "wecom_doc 已启用" : "未启用"}`,
+  ];
+}
+
 export function buildAgentStatusText({
   fromUser,
   config,
@@ -100,9 +157,11 @@ export function buildAgentStatusText({
   webhookBotPolicy,
   dynamicAgentPolicy,
   observabilityMetrics,
+  bindingsCount = 0,
 } = {}) {
   const proxyEnabled = Boolean(config?.outboundProxy);
   const voiceStatusLine = buildVoiceStatusLine(voiceConfig, voiceRuntimeInfo);
+  const readinessLines = buildAgentReadinessLines({ config, voiceConfig });
   const commandPolicyLine = commandPolicy.enabled
     ? `✅ 指令白名单已启用（${commandPolicy.allowlist.length} 条，管理员 ${commandPolicy.adminUsers.length} 人）`
     : "ℹ️ 指令白名单未启用";
@@ -141,6 +200,7 @@ export function buildAgentStatusText({
   const dynamicAgentPolicyLine = dynamicAgentPolicy.enabled
     ? `✅ 动态 Agent 路由已启用（mode=${dynamicAgentPolicy.mode}，用户映射 ${Object.keys(dynamicAgentPolicy.userMap || {}).length}，群映射 ${Object.keys(dynamicAgentPolicy.groupMap || {}).length}）`
     : "ℹ️ 动态 Agent 路由未启用";
+  const routePolicyLine = buildRoutePolicyStatusLine({ bindingsCount, dynamicAgentPolicy });
   const entryVisibilityLine = "✅ 微信插件入口联系人：Agent 模式可见（自建应用）";
   const observabilityLines = buildObservabilityStatusLines(observabilityMetrics);
 
@@ -153,8 +213,8 @@ export function buildAgentStatusText({
 插件版本：${pluginVersion}
 
 功能状态：
+${readinessLines.join("\n")}
 ✅ 文本消息
-✅ 图片发送/接收
 ✅ 消息分段 (2048字符)
 ✅ 命令系统
 ✅ Markdown 转换
@@ -172,6 +232,7 @@ ${streamManagerPolicyLine}
 ${webhookBotPolicyLine}
 ${webhookTargetsLine}
 ${dynamicAgentPolicyLine}
+${routePolicyLine}
 ${entryVisibilityLine}
 ${proxyEnabled ? "✅ WeCom 出站代理已启用" : "ℹ️ WeCom 出站代理未启用"}
 ${voiceStatusLine}
@@ -194,7 +255,10 @@ export function buildBotStatusText({
   webhookBotPolicy,
   dynamicAgentPolicy,
   observabilityMetrics,
+  config = {},
+  bindingsCount = 0,
 } = {}) {
+  const readinessLines = buildBotReadinessLines({ botConfig, config });
   const commandPolicyLine = commandPolicy.enabled
     ? `✅ 指令白名单已启用（${commandPolicy.allowlist.length} 条，管理员 ${commandPolicy.adminUsers.length} 人）`
     : "ℹ️ 指令白名单未启用";
@@ -227,6 +291,7 @@ export function buildBotStatusText({
   const dynamicAgentPolicyLine = dynamicAgentPolicy.enabled
     ? `✅ 动态 Agent 路由已启用（mode=${dynamicAgentPolicy.mode}，用户映射 ${Object.keys(dynamicAgentPolicy.userMap || {}).length}，群映射 ${Object.keys(dynamicAgentPolicy.groupMap || {}).length}）`
     : "ℹ️ 动态 Agent 路由未启用";
+  const routePolicyLine = buildRoutePolicyStatusLine({ bindingsCount, dynamicAgentPolicy });
   const entryVisibilityLine = "ℹ️ 微信插件入口联系人：Bot 模式通常不显示（请通过机器人会话/群聊入口触发）";
   const observabilityLines = buildObservabilityStatusLines(observabilityMetrics);
   return `📊 系统状态
@@ -237,6 +302,7 @@ export function buildBotStatusText({
 Bot Webhook：${botConfig.webhookPath}
 
 功能状态：
+${readinessLines.join("\n")}
 ✅ 原生流式回复（stream）
 ${commandPolicyLine}
 ${allowFromPolicyLine}
@@ -246,8 +312,10 @@ ${groupPolicyLine}
 ${fallbackPolicyLine}
 ${streamManagerPolicyLine}
 ${webhookBotPolicyLine}
+${longConnectionLine}
 ${webhookTargetsLine}
 ${dynamicAgentPolicyLine}
+${routePolicyLine}
 ${entryVisibilityLine}
 ${observabilityLines.status}
 ${observabilityLines.recent}`;

package/src/wecom/pairing.js

@@ -0,0 +1,188 @@
+import { normalizeWecomAllowFromEntry } from "../core.js";
+
+function normalizeAccountId(accountId) {
+  const normalized = String(accountId ?? "default").trim().toLowerCase();
+  return normalized || "default";
+}
+
+function uniqueAllowFrom(values = []) {
+  const out = [];
+  const seen = new Set();
+  for (const value of Array.isArray(values) ? values : []) {
+    const normalized = normalizeWecomAllowFromEntry(value);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+function getPairingRuntime(api) {
+  const pairing = api?.runtime?.channel?.pairing;
+  if (!pairing || typeof pairing !== "object") return null;
+  if (typeof pairing.readAllowFromStore !== "function") return null;
+  if (typeof pairing.upsertPairingRequest !== "function") return null;
+  if (typeof pairing.buildPairingReply !== "function") return null;
+  return pairing;
+}
+
+function matchesAllowFrom({ allowFrom = [], senderId = "", isWecomSenderAllowed } = {}) {
+  const normalizedAllowFrom = Array.isArray(allowFrom) ? allowFrom : [];
+  if (normalizedAllowFrom.includes("*")) return true;
+  if (typeof isWecomSenderAllowed !== "function") return false;
+  return isWecomSenderAllowed({
+    senderId,
+    allowFrom: normalizedAllowFrom,
+  });
+}
+
+export async function readWecomPairingAllowFromStore({ api, accountId = "default" } = {}) {
+  const pairing = getPairingRuntime(api);
+  if (!pairing) return [];
+  try {
+    const storeEntries = await pairing.readAllowFromStore({
+      channel: "wecom",
+      accountId: normalizeAccountId(accountId),
+    });
+    return uniqueAllowFrom(storeEntries);
+  } catch (err) {
+    api?.logger?.warn?.(`wecom: failed to read pairing store: ${String(err?.message || err)}`);
+    return [];
+  }
+}
+
+export async function resolveWecomDirectMessageAccess({
+  api,
+  accountId = "default",
+  dmPolicy = {},
+  allowFromPolicy = {},
+  normalizedFromUser = "",
+  isAdminUser = false,
+  isWecomSenderAllowed,
+} = {}) {
+  const mode = String(dmPolicy?.mode ?? "open").trim().toLowerCase() || "open";
+  const normalizedSender = normalizeWecomAllowFromEntry(normalizedFromUser);
+  const configuredAllowFrom = uniqueAllowFrom(dmPolicy?.allowFrom);
+  const baseAllowFrom = Array.isArray(allowFromPolicy?.allowFrom) ? allowFromPolicy.allowFrom : [];
+  const senderAllowedByBasePolicy =
+    isAdminUser ||
+    matchesAllowFrom({
+      senderId: normalizedSender,
+      allowFrom: baseAllowFrom,
+      isWecomSenderAllowed,
+    });
+
+  if (mode === "deny") {
+    return {
+      decision: "block",
+      reason: "dm-deny",
+      rejectText: dmPolicy?.rejectMessage || "当前渠道私聊已关闭，请联系管理员。",
+      configuredAllowFrom,
+      effectiveAllowFrom: configuredAllowFrom,
+      storeAllowFrom: [],
+    };
+  }
+
+  if (mode === "open") {
+    return {
+      decision: senderAllowedByBasePolicy ? "allow" : "block",
+      reason: senderAllowedByBasePolicy ? "dm-open" : "allowFrom",
+      rejectText: senderAllowedByBasePolicy
+        ? ""
+        : allowFromPolicy?.rejectMessage || "当前账号未授权，请联系管理员。",
+      configuredAllowFrom,
+      effectiveAllowFrom: configuredAllowFrom,
+      storeAllowFrom: [],
+    };
+  }
+
+  if (mode === "allowlist") {
+    const allowed =
+      isAdminUser ||
+      matchesAllowFrom({
+        senderId: normalizedSender,
+        allowFrom: configuredAllowFrom,
+        isWecomSenderAllowed,
+      });
+    return {
+      decision: senderAllowedByBasePolicy && allowed ? "allow" : "block",
+      reason: !senderAllowedByBasePolicy ? "allowFrom" : allowed ? "dm-allowlist" : "dm-allowlist-blocked",
+      rejectText: !senderAllowedByBasePolicy
+        ? allowFromPolicy?.rejectMessage || "当前账号未授权，请联系管理员。"
+        : dmPolicy?.rejectMessage || "当前私聊账号未授权，请联系管理员。",
+      configuredAllowFrom,
+      effectiveAllowFrom: configuredAllowFrom,
+      storeAllowFrom: [],
+    };
+  }
+
+  if (!senderAllowedByBasePolicy) {
+    return {
+      decision: "block",
+      reason: "allowFrom",
+      rejectText: allowFromPolicy?.rejectMessage || "当前账号未授权，请联系管理员。",
+      configuredAllowFrom,
+      effectiveAllowFrom: configuredAllowFrom,
+      storeAllowFrom: [],
+    };
+  }
+
+  const storeAllowFrom = await readWecomPairingAllowFromStore({
+    api,
+    accountId,
+  });
+  const effectiveAllowFrom = uniqueAllowFrom([...configuredAllowFrom, ...storeAllowFrom]);
+  const allowed =
+    isAdminUser ||
+    matchesAllowFrom({
+      senderId: normalizedSender,
+      allowFrom: effectiveAllowFrom,
+      isWecomSenderAllowed,
+    });
+  return {
+    decision: allowed ? "allow" : "pairing",
+    reason: allowed ? "dm-pairing-approved" : "dm-pairing",
+    rejectText: allowed ? "" : dmPolicy?.rejectMessage || "当前私聊需先完成配对审批。",
+    configuredAllowFrom,
+    effectiveAllowFrom,
+    storeAllowFrom,
+  };
+}
+
+export async function issueWecomPairingChallenge({
+  api,
+  accountId = "default",
+  fromUser = "",
+  normalizedFromUser = "",
+  sendPairingReply,
+} = {}) {
+  const pairing = getPairingRuntime(api);
+  const senderId = normalizeWecomAllowFromEntry(normalizedFromUser || fromUser);
+  if (!pairing || !senderId || typeof sendPairingReply !== "function") {
+    return { created: false, unsupported: true };
+  }
+
+  const { code, created } = await pairing.upsertPairingRequest({
+    channel: "wecom",
+    accountId: normalizeAccountId(accountId),
+    id: senderId,
+    meta: {
+      name: String(fromUser ?? "").trim() || undefined,
+    },
+  });
+  if (!created) {
+    return { created: false, code };
+  }
+
+  const replyText = pairing.buildPairingReply({
+    channel: "wecom",
+    idLine: `Your WeCom user id: ${senderId}`,
+    code,
+  });
+  try {
+    await sendPairingReply(replyText);
+  } catch (err) {
+    api?.logger?.warn?.(`wecom: pairing reply failed: ${String(err?.message || err)}`);
+  }
+  return { created: true, code, replyText };
+}

package/src/wecom/plugin-constants.js

@@ -1,5 +1,5 @@
 export const MAX_REQUEST_BODY_SIZE = 1024 * 1024;
-export const PLUGIN_VERSION = "2.0.1";
+export const PLUGIN_VERSION = "2.1.0";
 export const WECOM_TEMP_DIR_NAME = "openclaw-wechat";
 export const WECOM_TEMP_FILE_RETENTION_MS = 30 * 60 * 1000;
 export const WECOM_MIN_FILE_SIZE = 5;