echo-lgtm

dsh-plugin-wechat-official

Name: dsh-plugin-wechat-official
Author: echo-lgtm

DeepSeek Harness 微信 ClawBot 渠道插件：通过腾讯官方 iLink 接口让用户在个人微信中与 DSH Agent 对话

Stars: 1
Language: JavaScript
Created: Aug 15, 2026
Updated: Aug 15, 2026

Notify

GitHub repo

Introduction

dsh-plugin-wechat-official

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

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

工作原理

微信用户 ──▶ 微信 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 立即重连，最后时限强制重连，全程不断线
按用户串行	同一用户的消息按顺序处理，回复不会交错错位

前置条件

一个开通了「微信 ClawBot 插件功能」的微信个人账号。ClawBot 是微信官方向用户提供的连接第三方 AI 服务的功能，在微信内按提示「连接」并同意《微信ClawBot功能使用条款》后即可使用（本插件是条款意义上的「第三方 AI 服务提供方」）。
DeepSeek Harness（dsh CLI）与 web profile 可正常运行（插件作为宿主插件挂载到 web profile 进程）。
Node.js ≥ 22（DSH 本身要求）。
运行 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）。

配置

字段	默认值	说明
`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 可在一分钟内跑完整个续连流程。

首次运行（扫码登录）

启动 dsh web，日志中会出现：

wechat-clawbot: starting QR login…
wechat-clawbot: scan QR in WeChat → https://…
wechat-clawbot: QR url saved to …/qrcode-url.txt

用手机微信打开该链接（或在微信内扫描二维码），按提示「连接」并确认。
日志出现 wechat-clawbot: login OK (bot …) 后，即可在微信中向该机器人发送消息。
凭证自动保存到 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。

合规与风险提示

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

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