微信官方通道插件echo-lgtm/dsh-plugin-wechat-official

dsh-plugin-wechat-official

DeepSeek Harness 微信 ClawBot 渠道插件 —— 通过腾讯官方开放的 微信 ClawBot 插件功能（iLink 协议），让用户在个人微信中直接与 DeepSeek Harness Agent 对话。

✅ 全部基于腾讯官方通道（ilinkai.weixin.qq.com），不使用任何个人微信逆向协议、网页自动化、Hook 客户端或其它可能导致封号的非官方方案。
底层协议与 openclaw 的微信渠道插件 @tencent-weixin/openclaw-weixin 同一套（HTTP/JSON，腾讯仅作为消息管道，不存储输入输出内容）。

目录

- 工作原理
- 前置条件
- 安装
- 配置
- 首次运行（扫码登录）
- 使用
- 连接续期（24 小时）
- 访问控制
- 合规与风险提示
- 常见问题
- 项目结构
- 开发与测试
- 参考

工作原理

微信用户 ──▶ 微信 ClawBot（腾讯官方 iLink 服务）
│  getupdates 长轮询（游标 get_updates_buf）
▼
dsh-plugin-wechat-official（本插件，运行在 DSH 进程中）
│  文本 → createUserMessage → followup
▼
DSH Agent 会话（每个微信用户独立会话，持久化可恢复）
│  回复文本 ← assistant/message 事件
▼
sendmessage（必须回带 context_token 关联对话窗口）
│  sendtyping「正在输入」状态
▼
微信用户 ◀── 收到 Agent 回复

关键机制：

| 机制 | 说明 |
|---|---|
| 官方通道 | 登录走 get_bot_qrcode / get_qrcode_status 扫码；收消息走 getupdates 长轮询；回消息走 sendmessage |
| 会话关联 | 每条入站消息带 context_token，回复时必须原样回带，否则消息无法关联到对话窗口 |
| 独立会话 | 每个微信用户对应一个 DSH Agent 会话（id 由用户 id 派生），历史经 sessionPersistence 持久化，重启可恢复 |
| 正在输入 | 通过 getconfig 获取 typing_ticket 后调用 sendtyping（status 1/2）显示「正在输入」 |
| 24h 续连 | iLink 连接约 24 小时有效，到期前提醒最近联系人，可回复 Y 立即重连，最后时限强制重连，全程不断线 |
| 按用户串行 | 同一用户的消息按顺序处理，回复不会交错错位 |

前置条件

1. 一个开通了「微信 ClawBot 插件功能」的微信个人账号。ClawBot 是微信官方向用户提供的连接第三方 AI 服务的功能，在微信内按提示「连接」并同意《微信ClawBot功能使用条款》后即可使用（本插件是条款意义上的「第三方 AI 服务提供方」）。
2. DeepSeek Harness（dsh CLI）与 web profile 可正常运行（插件作为宿主插件挂载到 web profile 进程）。
3. Node.js ≥ 22（DSH 本身要求）。
4. 运行 DSH 的机器可访问 ilinkai.weixin.qq.com（出站网络）。无需公网 IP / 域名 / 端口映射 —— ClawBot 是插件主动长轮询拉取消息，不需要微信回调你的服务器。

安装

1. 安装依赖包到 web profile

克隆本仓库
git clone https://github.com/echo-lgtm/dsh-plugin-wechat-official.git
cd dsh-plugin-wechat-official

安装到 DSH web profile
dsh plugin --profile web add file:$(pwd)

等价于在 ~/.dsh/profiles/web 下执行 pnpm add file:。

2. 挂载插件行

编辑 ~/.dsh/profiles/web/cordis.patch.yml，追加（把示例值替换成你的配置）：

- insert:
- id: wechat-clawbot
name: 'dsh-plugin-wechat-official'
config:
扫码登录后凭证的存储目录（默认 $DSH_HOME/wechat-clawbot，可留空）
storageDir: ''
启动时自动恢复会话 / 无凭证时自动进入扫码登录
autoLogin: true
二维码展示：log（打印链接）| file（写 qrcode-url.txt）| both（默认）
qrcodeOutput: 'both'
访问控制：open | allowlist | disabled
dmPolicy: 'open'
allowFrom: []
Agent 工作目录（绝对路径；留空使用 DSH 进程当前目录）
agentCwd: ''

3. 启动

dsh web

首次启动会在日志中打印二维码链接（并写入 /qrcode-url.txt）。

配置

| 字段 | 默认值 | 说明 |
|---|---|---|
| storageDir | $DSH_HOME/wechat-clawbot | 凭证与二维码文件存储目录 |
| autoLogin | true | 启动时自动恢复已保存会话；无凭证时自动进入扫码登录 |
| qrcodeOutput | both | 二维码展示方式：log / file / both |
| qrcodeScanTimeoutMs | 600000 | 等待扫码的最长时间（毫秒） |
| sessionDurationMs | 86400000 | iLink 连接有效期（毫秒，约 24 小时） |
| reconnectWarningBeforeMs | 7200000 | 到期前多久向最近联系人发送重连提醒（毫秒） |
| reconnectReminderIntervalMs | 1800000 | 用户回复 N 后再次提醒的间隔（毫秒） |
| reconnectForceBeforeMs | 1800000 | 到期前多久开始强制重连（毫秒） |
| longPollTimeoutMs | 38000 | 长轮询超时（毫秒，微信最多 hold 35 秒） |
| dmPolicy | open | 访问控制：open（所有人）/ allowlist（仅 allowFrom）/ disabled（关闭对话） |
| allowFrom | [] | allowlist 模式下允许的用户 id 列表（形如 xxx@im.wechat） |
| renderMarkdown | true | Agent 回复的 Markdown 是否转为微信友好的纯文本 |
| welcomeText | 你好，我是 DeepSeek Harness Agent… | 新用户首次对话欢迎语 |
| agentCwd | DSH 进程 cwd | Agent 工作目录 |

连接参数（sessionDurationMs 等）如需调小测试，例如 sessionDurationMs: 300000, reconnectWarningBeforeMs: 60000, reconnectReminderIntervalMs: 30000, reconnectForceBeforeMs: 60000 可在一分钟内跑完整个续连流程。

首次运行（扫码登录）

1. 启动 dsh web，日志中会出现：
wechat-clawbot: starting QR login…
wechat-clawbot: scan QR in WeChat → https://…
wechat-clawbot: QR url saved to …/qrcode-url.txt

2. 用手机微信打开该链接（或在微信内扫描二维码），按提示「连接」并确认。
3. 日志出现 wechat-clawbot: login OK (bot …) 后，即可在微信中向该机器人发送消息。
4. 凭证自动保存到 storageDir/session.json（0600 权限），下次启动自动恢复，无需重复扫码。

使用

在微信中向机器人发送消息：

- 直接发文字 → 转发给 DSH Agent，回复经 sendmessage 送达，期间对方可见「正在输入」。
- 发语音 → 若微信已附带转写文字，则以 [语音] 转写内容 形式转发给 Agent。
- 发图片 / 文件 / 视频 → 以占位描述（[图片] 等）转发给 Agent，由 Agent 决定如何回应。
- 内置指令：

| 指令 | 作用 |
|---|---|
| /help 或 /指令 | 查看指令列表 |
| /time | 查询当前连接剩余时间 |
| /status | 查看 Bot 运行状态 |
| /重新连接 | 立即重新连接（需回复 Y 确认） |

每个用户拥有独立的 Agent 会话（带完整对话历史），也可在 DSH Web UI 的会话列表中查看。

连接续期（24 小时）

iLink 连接有效期约 24 小时。插件在到期前约 2 小时向最近联系人发送提醒：

[提醒] 连接还剩约 22.0 小时到期，是否现在重新连接？回复 Y 立即重连，N 稍后提醒

- 回复 Y → 立即重连：插件向该联系人推送新二维码，扫码确认后 token 原子替换，连接无缝切换。
- 回复 N → 按 reconnectReminderIntervalMs 间隔再次提醒。
- 到达 reconnectForceBeforeMs 时限 → 自动强制重连。
- 意外会话失效（token 过期）→ 自动清除凭证并重新进入扫码登录。

访问控制

- dmPolicy: 'open'（默认）：任何能向该机器人发消息的微信用户均可对话。
- dmPolicy: 'allowlist'：仅 allowFrom 中列出的用户 id 可对话，其余用户收到「没有权限」提示。
- dmPolicy: 'disabled'：关闭对话能力（仅保留指令与重连相关消息）。

用户 id 形如 o9cq800kum_xxx@im.wechat。可先以 open 模式运行，用 /status 或日志查看来访用户 id，再收紧为 allowlist。

合规与风险提示

1. 本插件只使用腾讯官方 ClawBot 接口，但请务必遵守《微信ClawBot功能使用条款》与《微信个人账号使用规范》：不得利用该功能绕过/破解微信技术保护措施、不得从事违法违规行为。
2. 腾讯仅作为消息管道，不存储输入输出内容；接入的 AI 服务（即 DSH Agent）由你自行负责，输出结果责任自负。
3. 腾讯有权对连接的第三方 AI 服务进行识别、限流甚至阻断（条款 4.7 / 7.2），不建议把核心业务完全依赖该通道，应保留降级方案。
4. 请妥善保管 storageDir/session.json（内含 bot token）。

常见问题

| 问题 | 处理 |
|---|---|
| 启动后没有看到二维码 | 检查日志是否出现 starting QR login…；若 storageDir 下有旧 session.json 且仍有效则直接恢复，不会重新登录。删除 session.json 可强制重新登录 |
| 发送消息没有回复 | 确认日志中是否出现 收到消息 / deliver reply；检查 dmPolicy 是否拦截；确认 Agent 服务（agents / agentLoop）可用 |
| 回复没有进入对话窗口 | 该现象通常是 context_token 丢失或过期——本插件始终回带用户最新入站消息的 context_token |
| 提示「连接即将到期」 | 正常现象，按提示回复 Y 重连即可；也可用 /重新连接 手动触发 |
| 收不到消息、日志持续报错 | 检查出站网络能否访问 ilinkai.weixin.qq.com；token 可能已失效，删除 session.json 后重启重新扫码 |

项目结构

dsh-plugin-wechat-official/
├── package.json            # 插件包定义（main 指向 lib/index.js，peerDeps 为 DSH 包）
├── cordis.patch.yml        # DSH profile 插件行声明（- insert: 条目）
├── lib/
│   ├── index.js            # Cordis 插件入口：Config schema / apply / 生命周期
│   ├── ilink.js            # iLink ClawBot 协议客户端（登录/长轮询/sendmessage/typing）
│   ├── channel.js          # 频道运行时：登录生命周期/轮询循环/指令/重连/访问控制
│   ├── bridge.js           # DSH Agent 桥接：会话映射/入队/回复提取（复用 DSH 核心）
│   ├── markdown.js         # Markdown → 微信友好纯文本
│   └── store.js            # 凭证持久化（原子写 + 0600）
├── scripts/
│   └── smoke.mjs           # 冒烟测试：本地模拟 iLink 服务器跑通全链路
├── test/                   # node:test 单元测试（ilink/markdown/bridge/channel）
└── README.md

开发与测试

npm run check    # 语法检查
npm test         # 单元测试（32 个用例）
npm run smoke    # 冒烟测试：本地模拟 iLink 服务器，验证登录→收消息→typing→回复全链路

参考

- OpenClaw 微信渠道文档：
- 微信 ClawBot 使用条款（协议全文）：
- iLink 协议技术解析：
- 官方插件包（腾讯）：