# 微信渠道接入

接入微信ClawBot，完成 OpenClaw 机器人配置。

## 核心原则

- **严格按步骤走，不要加戏。**
- **二维码字符图和备用链接必须写进文字回复，不能只留在 bash 工具输出里。**
- **不要自动轮询。** 给完二维码等用户说"扫完了"再轮询。

---

## 常见踩坑

### 扫码成功但 OpenClaw 仍显示 `no token`

**原因**：凭证文件尚未写入，或网关未重启。

**解决方案**：检查 `~/.openclaw/openclaw-weixin/accounts/` 下的账号文件，若已存在则重启网关：

```bash
openclaw gateway restart
```

---

## Step 4：检查插件，未装则装

```bash
ls ~/.openclaw/extensions/openclaw-weixin/package.json 2>/dev/null && echo "INSTALLED" || echo "NOT_INSTALLED"
```

- `INSTALLED` → 跳到 Step 5
- `NOT_INSTALLED` → 安装：

```bash
openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
```

装完验证 `ls ~/.openclaw/extensions/openclaw-weixin/package.json`，确认 `INSTALLED` 后继续。

---

## Step 5：获取二维码并渲染

**5a. 获取二维码数据：**

```bash
curl -s "https://ilinkai.weixin.qq.com/ilink/bot/get_bot_qrcode?bot_type=3"
```

从返回 JSON 提取：

- `qrcode` — 保存，Step 6 轮询用
- `qrcode_img_content` — 二维码页面链接

**5b. 用 qrcode-terminal 渲染字符二维码：**

```bash
node -e "
const qt = require(require('path').join(require('os').homedir(), '.openclaw/extensions/openclaw-weixin/node_modules/qrcode-terminal'));
qt.generate('<qrcode_img_content>', {small: true}, function(qr){ console.log(qr); });
"
```

**5c. 将以下内容完整写进文字回复（把实际字符二维码和链接替换进去）：**

---

使用**微信**扫一扫下面的二维码：

```
<上一步命令输出的字符二维码，原样粘贴>
```

如果二维码无法识别，请在**电脑浏览器**打开以下链接后扫码：
`<qrcode_img_content 的值>`

扫完在手机上确认登录，完成后告诉我"ok"。⏱ 有效期约 1 分钟。

---

然后**停下来，等用户确认**。

---

## Step 6：用户确认后 → 轮询状态

```bash
curl -s "https://ilinkai.weixin.qq.com/ilink/bot/get_qrcode_status?qrcode=<qrcode>"
```

| status      | 处理                                                               |
| ----------- | ------------------------------------------------------------------ |
| `wait`      | 等 3 秒再 poll                                                     |
| `scaned`    | 告诉用户"已扫码，请在手机上确认登录"                               |
| `confirmed` | 成功！提取 `ilink_bot_id`、`bot_token`、`baseurl`、`ilink_user_id` |
| `expired`   | 从 Step 5 重来                                                     |

---

## Step 7：写入凭证（confirmed 后必须执行）

将 `ilink_bot_id` 中的 `@` → `-`、`.` → `-` 得到 `accountId`（例：`a34b410e2e6f@im.bot` → `a34b410e2e6f-im-bot`）。

用 Write 工具直接写入以下两个文件（将实际值填入）：

**文件 1**：`~/.openclaw/openclaw-weixin/accounts/<accountId>.json`
```json
{
  "token": "<ilink_bot_id>:<bot_token>",
  "savedAt": "<当前 ISO 时间>",
  "baseUrl": "<baseurl>",
  "userId": "<ilink_user_id>"
}
```

**文件 2**：`~/.openclaw/openclaw-weixin/accounts.json`

先读取现有内容（若文件不存在则视为空数组），将 `<accountId>` 加入数组后写回：
```json
["<accountId>"]
```

写完后执行权限修正：
```bash
chmod 600 ~/.openclaw/openclaw-weixin/accounts/<accountId>.json
```

---

## Step 8：重启 Gateway

```bash
openclaw gateway restart
```

---

## Step 9：验证并提示用户

执行 `openclaw status` 确认 channel 状态为 `OK`，然后输出：

---

## 微信连接结果

- ✅ 状态：已绑定成功
- ✅ Gateway：已重启
- ilink_bot_id: `<ilink_bot_id>`
- ilink_user_id: `<ilink_user_id>`

现在可以直接在微信里发消息了 🎉

---

到此为止。不要再做任何额外操作。

## 绝对禁止

- 禁止自动开轮询（等用户说"扫完了 / ok"）
- 禁止手动改写 `openclaw.json`
- 禁止跳过写凭证步骤（不写凭证插件无法连接）
- 禁止把二维码和链接只放在 bash 工具输出里——必须原样写进文字消息
