# 微信联调指南（dsh-im-weixin）

> 目标：**只看这一篇文档，就能把 dsh-im-weixin 从零跑通**——在微信里指挥 DeepSeek Harness 的真实 agent。
>
> 走的是腾讯**官方 iLink 个人微信机器人**通道（协议源自腾讯开源项目
> [Tencent/openclaw-weixin](https://github.com/Tencent/openclaw-weixin)），
> `getupdates` 长轮询，**免公网**（不需要公网 IP / 隧道 / 回调 URL）。
>
> 全文约 10 分钟。分四部分：
> ① 确认微信账号资格（最关键，先看这个）
> ② 安装插件 + 扫码绑定（约 2 分钟）
> ③ 在微信里使用（派活 / 审批 / 查状态）
> ④ 常见问题排查

---

## ① 确认微信账号资格（先看这个，否则白装）

**这是平台硬性要求，插件无法绕过**：腾讯分批开放「微信机器人」功能，
你的手机微信账号必须已经拿到资格：

1. 打开手机微信 → **我 → 设置 → 插件**
2. 如果里面能看到**微信机器人**（或类似入口）→ 恭喜，可以直接用
3. 看不到入口 = 账号还没在开放名单里 → 扫码和连接都会失败，只能等腾讯分批放量

> ⚠️ 不要相信任何"帮你开通"的第三方服务——微信机器人是腾讯官方分批开放，
> 花钱找人开号 = 封号风险。没有入口就先收藏本文，等开放了再回来。

另外：绑定后**机器人绑定的是扫码的那个微信号**，收发消息都走这个号；
一个账号绑定一个机器人，重复扫码会提示"已绑定"。

## ② 安装插件 + 扫码绑定（网页方式，约 2 分钟）

```sh
# 1. 装插件（需先装核心 dsh-im）
dsh plugin --profile web add dsh-im dsh-im-weixin -w
```

绑定（**推荐网页方式，不碰终端**）：

1. 启动 `dsh web`，打开浏览器 **设置 → 插件 → 微信** 页签
2. 点「**📱 扫码绑定 | Scan to bind**」
3. 网页出现**二维码** → 用**手机微信**扫一扫 → 手机上确认
4. 如果手机显示**配对数字** → 在网页输入框填入这串数字 → 点「提交」
5. 页面显示「🎉 绑定成功」→ **重启 `dsh web`**

> 没有网页时用终端方式：`npx -y dsh-im-weixin-qr`，流程一样（配对数字在终端输入）。
>
> 凭据写入 Host 本机 `$DSH_HOME/dsh-im/weixin-credentials.json`（仅本机可读），
> **bot_token 不会出现在浏览器里**，也无需设置任何环境变量。
> 想解绑？删掉凭据文件即可。

## ③ 在微信里使用

| 你在微信里发 | 会发生什么 |
|---|---|
| `/new` | 创建新会话，agent 就绪 |
| 直接发任务，如 `列出当前目录内容` | agent 执行，结果发回微信 |
| 任务里触发危险命令（如删除文件） | 收到**文本审批**：`🔐 审批 #id` + `/approve <id> yes|no`（微信没有按钮） |
| 回复 `/approve <id> yes` 或 `/approve <id> no` | 批准 / 拒绝 |
| `/status` | 渠道连接状态、会话列表、等待中的审批 |
| `/log` | 把最近一次任务的完整输出发回 |
| `/mute` `/unmute` | 关闭/打开本聊天通知 |
| `/help` | 命令列表 |

> 只支持**文字消息**，以及微信已自带转写结果的**语音**；图片/文件/视频暂不送入 agent。

## ④ 常见问题排查

| 现象 | 原因与解决 |
|---|---|
| 扫码时提示"已绑定" | 这个微信账号绑过机器人了（或绑定过其他机器人）。解绑后重试，或换一个微信号 |
| 连接报 `notifystart failed` | 大概率是账号没有微信机器人功能：检查 ①「我 → 设置 → 插件」；有入口还失败就把终端报错截图发我 |
| 二维码过期 | 重新运行 `npx -y dsh-im-weixin-qr` 生成新二维码 |
| 配对数字输错多次 | 会提示"配对数字多次错误"，重新运行扫码 |
| 能收到消息但回复失败 | 看终端报错里的平台错误码（`ret=`）；联系维护者时附上完整报错 |
| bot 回消息报"未授权" | 首次接触触发信任流程：管理员 `/trust weixin:<wxid>` 授权（见主 README 安全说明） |

---

## 协议来源

iLink 请求格式基于腾讯官方 MIT 项目 [Tencent/openclaw-weixin](https://github.com/Tencent/openclaw-weixin)
2.4.6 适配，本插件用原生 fetch 重新实现，未引入 OpenClaw 运行时。