微信 ClawBot 插件完整指南——从安装到实战

腾讯官方开放微信个人号 Bot API 了！无需 Hook、不封号，10 分钟让 AI 助理在微信里陪你聊天。

本文特色： 理论 + 实测，所有步骤已验证，照做即可。

测试环境：

• 系统：macOS 24.6.0 (Darwin x64)

• Node.js: v25.1.0

• OpenClaw: v2026.3.13

• 插件：@tencent-weixin/openclaw-weixin v1.0.3

• 微信：iOS 最新版

本文基于： OpenClaw v2026.3 + @tencent-weixin/openclaw-weixin v1.0.3

一、这是什么？

2026 年，腾讯终于迈出了历史性的一步——通过微信 ClawBot 插件，首次为个人号提供官方合法的 Bot API。

底层协议名为 iLink（智联），以 @tencent-weixin/openclaw-weixin npm 包的形式发布，作为 OpenClaw 的 Channel Plugin。

1.1 微信机器人发展史

微信个人号的机器人开发，从此不再是”猫鼠游戏”：

1.2 核心能力

支持的：

• ✅ 官方开放，无需逆向

• ✅ 扫码登录，安全授权

• ✅ 文本、图片、语音、视频、文件

• ✅ “正在输入”状态

• ✅ 多账号同时在线

• ✅ 多 AI Agent 切换

不支持的：

• ⚠️ 不能主动推送（必须用户先发消息）

• ⚠️ 不能发送引用消息

• ⚠️ 仅支持 iOS 微信

二、快速开始（5 分钟）

2.1 一键安装

npx -y @tencent-weixin/openclaw-weixin-cli install

执行后会：


下载并安装插件到 ~/.openclaw/extensions/openclaw-weixin


自动启用插件


显示微信扫码登录二维码


2.2 扫码登录
终端会显示二维码，用iOS 微信扫描并确认授权。
如果二维码没显示，用浏览器打开链接：




https://liteapp.weixin.qq.com/q/XXXXX

2.3 重启 Gateway




openclaw gateway restart

2.4 开始聊天
在微信里找到 ClawBot 对话，发送任意消息，AI 会回复。
2.5 快速直通版本





你：npx -y @tencent-weixin/openclaw-weixin-cli install 我帮安装，并且将二维码显示出来，放便我扫码openclaw： 执行

缺点，一个微信只能绑定一个openclaw…….
另外不支持拉群
完成！

三、详细安装步骤
3.1 前置检查
确保 OpenClaw 已安装并运行：

# 检查版本
openclaw --version

# 检查 Gateway 状态
openclaw gateway status

如果没安装 OpenClaw，先执行：

npm install -g openclaw@latest

3.2 安装方式
方式 1：一键安装（推荐）

npx -y @tencent-weixin/openclaw-weixin-cli install

方式 2：手动安装

# 1. 安装插件
openclaw plugins install "@tencent-weixin/openclaw-weixin"

# 2. 启用插件
openclaw config set plugins.entries.openclaw-weixin.enabled true

# 3. 扫码登录
openclaw channels login --channel openclaw-weixin

# 4. 重启 Gateway
openclaw gateway restart

3.3 安装过程实录
以下是实际安装时的输出：

[openclaw-weixin] 已找到本地安装的 openclaw
[openclaw-weixin] 正在安装插件...

Downloading @tencent-weixin/openclaw-weixin…
Extracting .../tencent-weixin-openclaw-weixin-1.0.3.tgz…

WARNING: Plugin "openclaw-weixin" contains dangerous code patterns: 
Environment variable access combined with network send

Installing to /Users/cuihao/.openclaw/extensions/openclaw-weixin…
Installed plugin: openclaw-weixin
Restart the gateway to load plugins.

正在启动微信扫码登录...
使用微信扫描以下二维码，以完成连接：
[二维码]

3.4 关于安全警告
安装时会显示：

WARNING: Plugin "openclaw-weixin" contains dangerous code patterns

这是正常的。因为插件需要：


访问环境变量（读取配置）


发送网络请求（调用微信 API）


这是官方插件，代码开源可查，可以放心使用。
3.5 清理无效配置
安装时可能提示：

plugins.entries.openclaw-tavily: plugin not found

清理方法：

openclaw config delete plugins.entries.openclaw-tavily


四、配置说明
4.1 配置文件位置
插件配置在 ~/.openclaw/openclaw.json：

{
plugins: {
entries: {
"openclaw-weixin": {
enabled: true,
      },
    },
  },
}

4.2 多账号配置
如果需要多个微信同时在线：




openclaw channels login --channel openclaw-weixin

每次扫码会添加一个新账号。
4.3 上下文隔离
默认所有微信共享同一个 AI 记忆。如果想隔离：




openclaw config set agents.mode per-channel-per-peer

这样每个”微信账号 + 发送者”有独立记忆，避免串台。

五、使用指南
5.1 发送第一条消息
在微信里找到 ClawBot 对话，发送：




你好

AI 会回复：











你好！我是你的 AI 助理，已经住进你的微信了。我可以帮你：- 聊天解闷- 查询信息- 写代码、改 bug- 写文章、翻译- 还有很多...有什么需要尽管说！


5.2 切换 AI Agent
支持多个 AI Agent，通过命令切换：

/claude    # 切换到 Claude
/codex     # 切换到 Codex
/km        # 切换到 Kimi
/gm        # 切换到 Gemini
/oc        # 切换到 OpenClaw
/status    # 查看当前 Agent 状态
/help      # 查看帮助

示例：

/cc 帮我解释一下这段代码：[粘贴代码]

这会发送给 Claude 处理。
5.3 发送图片
你发图片给 AI：


在微信里直接发图片给 ClawBot


AI 会自动识别图片内容并回复


支持的格式： PNG、JPG、GIF（转静态）、WebP大小限制： 最大 20MB，建议 5MB 以内

AI 回复图片给你：
当 AI 回复包含图片（![](url)）时，插件会自动：


下载图片


AES-128-ECB 加密


上传到微信 CDN


作为图片消息发送


实际体验：


小图片（<500KB）：约 2-3 秒


中图片（500KB-2MB）：约 3-5 秒


大图片（>2MB）：约 5-10 秒，可能失败



示例对话：
你：（发送一张猫的图片）
AI：

这是一只可爱的猫咪！看起来是：
- 品种：英短蓝猫
- 年龄：约 2-3 岁
- 状态：很放松，可能在晒太阳

需要我帮你做什么吗？

5.4 “正在输入”状态
AI 回复前会先显示”正在输入…”，让对话更自然。（这个确实是打分项目，不用科学上网了）
5.5 主动推送消息（HTTP API）
iLink 协议本身不能主动推送，但 WeClaw 提供了 HTTP API：
发送文本：

curl-X POST http://127.0.0.1:18011/api/send \
-H"Content-Type: application/json" \
-d'{"to": "user_id@im.wechat", "text": "你好，这是主动推送的消息"}'

发送图片：

curl-X POST http://127.0.0.1:18011/api/send \
-H"Content-Type: application/json" \
-d'{"to": "user_id@im.wechat", "media_url": "https://example.com/photo.png"}'

获取用户 ID： 在日志中查看，格式为 user_id@im.wechat

六、技术原理
6.1 协议架构

微信 iOS ←→ iLink 服务器 (ilinkai.weixin.qq.com) ←→ openclaw-weixin 插件 ←→ OpenClaw Gateway ←→ AI Agent

6.2 iLink API 端点
iLink 是一套纯 HTTP/JSON 协议，接入域名 ilinkai.weixin.qq.com：




端点
方法
用途
超时




ilink/bot/get_bot_qrcode
GET
获取登录二维码
–


ilink/bot/get_qrcode_status
GET
轮询扫码状态
35s


ilink/bot/getupdates
POST
长轮询收消息
35s


ilink/bot/sendmessage
POST
发送消息
15s


ilink/bot/getconfig
POST
获取配置（typing ticket）
10s


ilink/bot/sendtyping
POST
发送”正在输入”状态
10s


ilink/bot/getuploadurl
POST
获取 CDN 预签名上传地址
15s




6.3 鉴权机制


扫码登录获取 bot_token


每个请求带 Authorization: Bearer {token}


X-WECHAT-UIN：每次请求随机生成 uint32 → base64，防重放攻击


6.4 消息机制


长轮询（35s hold）+ 游标推进：类似 Telegram Bot API


回复必须带 context_token：关联到正确的对话窗口


不能主动推送：必须由用户先发消息触发


6.5 插件增强能力
@tencent-weixin/openclaw-weixin 在 iLink 协议之上做了大量增强：




能力
说明




Session Guard
检测到错误码 -14 时，自动暂停该账号 60 分钟


Config Cache
typing_ticket 按用户缓存 24 小时，失败时指数退避


Markdown → 纯文本
AI 返回的 markdown 自动转为微信友好的纯文本


SILK 语音转码
使用 silk-wasm 将微信 SILK 音频解码为 WAV


CDN 媒体加解密
AES-128-ECB 加密上传、下载解密


引用消息识别
读取 ref_msg 字段，格式化为 [引用：xxx]（只读）


Pairing 配对
扫码用户自动注册到 allowFrom 授权列表


Debug 全链路追踪
发送 /toggle-debug 开启，每条回复追加耗时报告




6.6 媒体处理流程
所有媒体（图片/语音/视频/文件）通过 CDN 传输，使用 AES-128-ECB 加密。
上传流程：


计算文件大小、MD5、加密后大小


调用 getUploadUrl 获取预签名 URL


AES 加密后 PUT 上传


返回 encrypt_query_param 用于消息引用



七、功能限制
7.1 支持的功能




功能
状态
说明




文本消息
✅
收发正常


图片消息
✅
支持 PNG/JPG/GIF/WebP，最大 20MB


语音消息
✅
SILK 转 WAV（24kHz 单声道）


视频消息
✅
CDN 传输


文件消息
✅
CDN 传输


“正在输入”状态
✅
typing_ticket 机制


引用消息识别
✅
ref_msg 字段解析（只读）


多账号
✅
支持同时在线


多 Agent 切换
✅
通过命令切换


主动推送
🟡
需调用 HTTP API




7.2 不支持的功能




功能
原因




安卓微信
协议仅对接 iOS


主动推送
iLink 协议限制


发送引用消息
ref_msg 字段只读，服务端忽略


群聊
尚未开放


GIF 动图
会转为静态图


图片编辑
无法裁剪/滤镜




7.3 重要限制
⚠️ 仅支持 iOS 微信 — 安卓、PC、Mac 客户端暂不支持
⚠️ 不能主动推送 — 必须用户先发消息，Bot 才能回复（HTTP API 除外）
⚠️ 腾讯保留管控权 — 可随时限速、拦截、终止服务
⚠️ 一个微信只能绑定一个 OpenClaw — iLink 协议限制

7.4 图片功能缺点（实测）
缺点 1：AI 回复图片速度慢


小图片（<500KB）：约 2-3 秒


中图片（500KB-2MB）：约 3-5 秒


大图片（>2MB）：约 5-10 秒，可能超时失败


缺点 2：GIF 动图会变静态
缺点 3：图片质量有损


微信 CDN 会压缩图片


原图 5MB，发送后可能变成 1-2MB


细节损失明显（尤其是文字截图）


缺点 4：加密计算耗时


AES-128-ECB 加密需要 CPU 计算


大图片会占用较多资源


缺点 5：下载失败无重试


如果 AI 返回的图片 URL 无法访问（比如临时链接过期），会直接失败



解决方案/建议：


让 AI 返回小图 — 请求时指定尺寸（如”生成 512×512 的图”）


用图床链接 — AI 返回稳定图床的链接，不要用过期的临时链接


接受文字描述 — 如果图片不重要，让 AI 用文字描述


本地查看 — AI 返回链接，你自己点开看（不通过微信 CDN）



八、安全建议
8.1 授权控制
扫码登录时，微信会显示授权提示，确认后才允许 Bot 接收你的消息。
建议：


只在自己微信上授权


定期检查已授权的 Bot


不再使用时在微信里取消授权


8.2 多账号隔离
如果多个微信账号同时在线，建议启用上下文隔离：

openclaw config set agents.mode per-channel-per-peer

8.3 日志审计
所有消息往来都会记录在 OpenClaw 日志中：

# 查看最近的微信消息日志
openclaw logs | grep wechat

8.4 环境变量配置
敏感信息建议用环境变量：

exportOPENCLAW_GATEWAY_URL="https://your-gateway.com"
exportOPENCLAW_GATEWAY_TOKEN="sk-xxx"


九、进阶玩法
9.1 接入多个 AI Agent
WeClaw 支持同时接入多个 AI Agent，在微信里通过命令切换：
配置文件 ~/.weclaw/config.json：

{
"default_agent": "claude",
"agents": {
"claude": {
"type": "acp",
"command": "/usr/local/bin/claude-agent-acp",
"model": "sonnet"
    },
"codex": {
"type": "acp",
"command": "/usr/local/bin/codex-acp"
    },
"openclaw": {
"type": "http",
"endpoint": "http://127.0.0.1:18789",
"api_key": "sk-xxx",
"model": "openclaw:main"
    }
  }
}

9.2 跳过权限确认（CLI 模式）
部分 Agent 默认需要交互式权限确认，在微信场景下无法操作。可通过 args 配置跳过：

{
"claude": {
"type": "cli",
"command": "/usr/local/bin/claude",
"args": ["--dangerously-skip-permissions"]
  },
"codex": {
"type": "cli",
"command": "/usr/local/bin/codex",
"args": ["--skip-git-repo-check"]
  }
}

⚠️ 注意： 这些参数会跳过安全检查，请了解风险后再启用。ACP 模式的 Agent 会自动处理权限，无需配置。
9.3 工作目录配置
通过 cwd 指定 Agent 的工作目录（workspace）：

{
"claude": {
"type": "cli",
"command": "/usr/local/bin/claude",
"cwd": "/home/user/my-project"
  }
}

不设置则默认为 ~/.weclaw/workspace。
9.4 后台服务运行
macOS (launchd)：

cpservice/com.fastclaw.weclaw.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.fastclaw.weclaw.plist

Linux (systemd)：

sudocpservice/weclaw.service /etc/systemd/system/
sudo systemctl enable --now weclaw

9.5 Docker 部署

# 登录（交互式，扫描二维码）
docker run -it-v ~/.weclaw:/root/.weclaw weclaw login

# 使用 HTTP Agent 启动
docker run -d--name weclaw \
-v ~/.weclaw:/root/.weclaw \
-eOPENCLAW_GATEWAY_URL=https://api.example.com \
-eOPENCLAW_GATEWAY_TOKEN=sk-xxx \
  weclaw

# 查看日志
docker logs -f weclaw


十、日志与调试
10.1 查看日志

# OpenClaw 日志
openclaw logs

# 过滤微信相关
openclaw logs | grep wechat

# 查看插件日志
cat ~/.openclaw/logs/openclaw-weixin.log

10.2 开启 Debug 模式
在微信里发送：

/toggle-debug

之后每条回复会附带完整耗时分解报告。
10.3 查看插件状态

openclaw plugins list

应该能看到：

✓ openclaw-weixin (enabled)


十一、常见问题
Q1: 扫码后一直显示”等待确认”怎么办？
原因： 网络问题或微信服务器延迟
解决：


检查网络连接


确保能访问 ilinkai.weixin.qq.com


重试扫码登录



Q1.5: 提示”账号已绑定其他 OpenClaw”
实际踩坑（2026-03-24）：
扫码后无法通信，原因是一个微信账号只能绑定一个 OpenClaw 实例。
症状：


扫码成功


但收不到消息/发不出消息


可能提示账号已在其他地方登录


原因：iLink 协议规定一个微信账号只能绑定一个 Bot 实例。如果你的微信之前绑定过其他 OpenClaw（比如家里的服务器、其他电脑），新设备无法同时绑定。
解决方案：
方案 A：解绑旧设备（推荐）


找到之前绑定该微信的 OpenClaw 设备


在那台设备上执行：

openclaw channels logout --channel openclaw-weixin



或者删除凭证文件：

rm ~/.openclaw/channels/openclaw-weixin/*.json



然后在新设备重新扫码登录


方案 B：使用另一个微信账号


用家人的微信、小号等重新扫码


方案 C：联系微信解绑


在微信里找 ClawBot 对话


发送 /logout 或 /unbind（如果支持）


预防：


绑定前确认该微信没有在其他 OpenClaw 实例上使用


多台设备测试时用不同微信账号



Q2: 消息收不到/发不出怎么办？
可能原因：


会话过期（错误码 -14）：重新扫码登录


网络问题：检查服务器能否访问微信 API


账号被限制：等待 60 分钟自动恢复


解决：

# 查看日志
openclaw logs | grep wechat

# 重新登录
openclaw channels login --channel openclaw-weixin


Q3: 安卓微信能用吗？
不能。 iLink 协议目前只对接 iOS 微信，安卓版本尚未开放。

Q4: 能主动给用户发消息吗？
iLink 协议本身不支持。 但可以通过 WeClaw 的 HTTP API 实现：

curl-X POST http://127.0.0.1:18011/api/send \
-H"Content-Type: application/json" \
-d'{"to": "user_id@im.wechat", "text": "主动消息"}'


Q5: 支持群聊吗？
暂不支持。 目前仅支持私聊，群聊功能尚未开放。

Q6: 消息有延迟吗？
正常 1-3 秒。 iLink 使用长轮询机制（35s hold），消息到达后服务器会立即响应。

十二、总结
12.1 安装体验
优点：


✅ 一键安装，非常简单


✅ 扫码登录，无需复杂配置


✅ 官方插件，稳定不封号


✅ 功能完整，支持多种媒体


不足：


❌ 仅支持 iOS 微信


❌ 不能主动推送


❌ 安全警告有点吓人（虽然正常）


❌ 一个微信只能绑定一个 OpenClaw 实例


12.2 图片功能体验
优点：


✅ 自动处理，无需手动操作


✅ 支持常见格式（PNG/JPG/WebP）


✅ AI 能识别你发的图片内容


缺点：


❌ AI 回复图片慢（2-10 秒）


❌ GIF 动图变静态


❌ 图片质量有损（微信压缩）


❌ 大图片可能失败


❌ 临时链接过期会失败


建议：


小图片体验很好


大图片建议用链接代替


重要图片建议本地保存


12.3 使用体验
好的地方：


AI 回复速度快（1-3 秒）


“正在输入”状态很自然


图片自动处理，无需手动操作


多 Agent 切换方便


待改进：


希望能支持安卓微信


希望能支持群聊


希望能主动推送消息


12.4 推荐使用场景


✅ 个人 AI 助理（随时聊天）


✅ 开发者（接入自己的服务）


✅ 客服机器人（自动回复常见问题）


✅ 工作流自动化（微信触发任务）


✅ 图片识别/分析（发图片问 AI）


12.5 不推荐场景


❌ 需要主动推送通知


❌ 需要群聊机器人


❌ 安卓微信用户


❌ 频繁收发大图片（慢且有损）


❌ 需要高质量图片传输



附录：相关资源


OpenClaw 官方文档


npm 包：@tencent-weixin/openclaw-weixin


WeClaw 项目


iLink 协议逆向分析


OpenClaw 系列文章汇总