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 小时）](#连接续期24-小时)
• [访问控制](#访问控制)
• [合规与风险提示](#合规与风险提示)
• [常见问题](#常见问题)
• [项目结构](#项目结构)
• [开发与测试](#开发与测试)
• [参考](#参考)

---

工作原理

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

关键机制：

---

前置条件

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

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

---

配置

> 连接参数（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 决定如何回应。
• 内置指令：

每个用户拥有独立的 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）。

---

常见问题

---

项目结构

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 微信渠道文档：<https://docs.openclaw.ai/zh-CN/channels/wechat>
• 微信 ClawBot 使用条款（协议全文）：<https://github.com/hao-ji-xing/openclaw-weixin/blob/main/protocol.md>
• iLink 协议技术解析：<https://github.com/hao-ji-xing/openclaw-weixin/blob/main/weixin-bot-api.md>
• 官方插件包（腾讯）：<https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin>