---

title: “OpenClaw 接入微信实测：一条命令让 AI 助手住进微信（2026 最新版）”
tags:

• AI助手
• OpenClaw
• 微信
• 效率工具
• 人工智能
  categories:
• AI工具
  description: “手把手教你用 OpenClaw + 腾讯官方 ClawBot 插件接入微信私聊，从环境准备、插件安装到扫码登录全程实录，附 iLink 协议原理、进阶配置和踩坑经验。”

---

导读：我用了大半年 OpenClaw 当个人 AI 助手，之前主要通过 Telegram 和 WebChat 跟它交互。2026 年 3 月腾讯官方出了微信插件 @tencent-weixin/openclaw-weixin，装完就能在微信里直接跟 AI 对话——走的是官方 iLink 协议，不是什么第三方 hook，稳定性和安全性都没得说。这篇文章记录了完整的接入过程、工作原理和我踩过的坑，希望能帮你少走弯路。

---

先搞清楚 OpenClaw 是什么

简单讲，OpenClaw 是一个开源的个人 AI 助手网关（Gateway），由奥地利开发者 Peter Steinberger（PSPDFKit 创始人）发起，目前在 GitHub 上有 230K+ Star、200+ 贡献者。它可以在一个进程里同时接入 WhatsApp、Telegram、Discord、Slack、iMessage、Signal、Microsoft Teams、飞书、钉钉等 22+ 聊天平台，后面统一对接一个 AI Agent。

你可以把它理解成一个"AI 助手的中枢"——不管你从哪个平台发消息，背后都是同一个 AI 在回复你。而且它是自托管的（Self-hosted），所有数据都跑在你自己的机器上，隐私完全可控。

我目前的配置：

• 部署方式：macOS 本地部署
• 模型：智谱 GLM-5.1（国内直连，延迟低）
• 日常交互：WebChat + 微信（以前用 Telegram，现在微信完全替代了）

本文适用版本：

组件	版本要求	推荐版本
OpenClaw	≥ 2026.3.22	最新稳定版
微信插件	2.x（对应 OpenClaw ≥ 2026.3.22）	@tencent-weixin/openclaw-weixin 2.4.3
Node.js	≥ 22.16	24.x LTS
微信客户端	iOS/Android 8.0.70+	最新版
操作系统	macOS 12+ / Ubuntu 22.04+ / Windows 10+	均可

💡 如果你用的是老版 OpenClaw（< 2026.3.22），插件 2.x 会报错，需要装 legacy 版本：openclaw plugins install @tencent-weixin/openclaw-weixin@legacy

---

为什么要用官方插件而不是第三方方案

在腾讯出官方插件之前，社区里有不少接入微信的方案，比如 WeChatPadPro、wxauto、WeChaty 等。我之前也折腾过，体验都不太好。这里做个对比，你就明白为什么官方插件是首选：

维度	旧方案（Hook/模拟协议）	官方 iLink 插件
合法性	违反微信服务协议，灰色地带	官方开放，合法合规
稳定性	每次微信更新可能失效	服务器端 API，稳定可靠
封号风险	高，频繁操作容易被风控	正常使用无封号风险
协议层	模拟 iPad/移动端协议	HTTP/JSON，标准接口
媒体支持	有限，大文件经常失败	图片/语音/文件/视频完整支持
群聊	需要特殊处理，容易出 bug	原生支持（后续版本开放）
维护成本	高，微信一更新就要跟着改	腾讯官方维护，跟着版本走就行

说白了，以前那些方案都是在"模拟"微信客户端的行为，本质上是在灰色地带跳舞。iLink 协议是腾讯官方开放的 Bot API，走的完全是正规路线。

---

工作原理：消息是怎么流转的

了解原理有助于排查问题。整个消息流转路径其实不复杂：

你（微信客户端）→ 微信服务器 → iLink 网关 → openclaw-weixin 插件 → OpenClaw Gateway → AI 模型

拆开来看：

1. 插件安装：openclaw plugins install 把 @tencent-weixin/openclaw-weixin 装到 OpenClaw 的插件目录
2. Gateway 加载：Gateway 启动时扫描插件清单，加载微信插件的入口点
3. 渠道注册：插件注册渠道 ID openclaw-weixin，告诉 Gateway “我能处理微信消息”
4. 扫码登录：openclaw channels login 启动二维码登录流程，通过 iLink API 获取 bot_token
5. 凭证存储：登录成功后，bot_token 保存在 OpenClaw 状态目录（~/.openclaw/ 下）
6. 消息监听：插件通过 iLink 的 getupdates 接口长轮询（hold 最多 35 秒），等待新消息
7. 消息路由：收到消息后规范化格式，路由到配置的 AI Agent
8. 回复发送：Agent 的回复通过插件的出站路径，调用 sendmessage 接口发回微信

这里面有个关键设计：每条收到的消息都带有一个 context_token，回复时必须原样带上，否则消息不会关联到正确的对话窗口。这个设计跟 Telegram Bot API 的思路类似。

---

环境准备：先把地基打好

在装插件之前，确保你的环境是就绪的。这一步很多人跳过，结果后面各种报错。

1. 检查 Node.js 版本

node --version
# 需要 >= 22.16，推荐 24.x LTS

如果版本太低：

# macOS 用 nvm 管理版本
nvm install 24
nvm use 24

# 或者直接从官网下载安装
# https://nodejs.org/

2. 安装或更新 OpenClaw

# 全新安装
npm install -g openclaw@latest

# 或者更新已有版本
npm update -g openclaw

# 确认版本
openclaw --version
# 应该显示 >= 2026.3.22

3. 首次使用：运行 onboarding

如果你是第一次用 OpenClaw，需要跑一下初始化向导：

openclaw onboard --install-daemon

这个命令会引导你完成：

• 选择 AI 模型和配置 API Key
• 安装 Gateway 守护进程（macOS 用 launchd，Linux 用 systemd）
• 初始化配置文件 ~/.openclaw/openclaw.json

4. 确认 Gateway 在运行

# 启动 Gateway
openclaw gateway start

# 检查状态
openclaw gateway status
# 应该显示 running

⚠️ Gateway 必须在运行状态下才能安装插件和扫码登录。如果状态不是 running，先排查 Gateway 的问题。

---

安装插件：两种方式任选

方式一：快捷安装（推荐新手）

一行命令搞定全部——安装、启用、扫码、重启，全自动：

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

这个命令做了这些事：

1. 检测你本地的 OpenClaw 版本
2. 自动匹配插件版本（2.x 还是 1.x）
3. 安装并启用插件
4. 弹出二维码让你扫码登录
5. 重启 Gateway

整个过程大概 2-3 分钟。不过如果你是第一次操作，建议先看完下一节的注意事项再扫。

方式二：手动安装（推荐老手）

手动安装的好处是每一步都可控，出了问题容易定位：

# 第 1 步：安装插件
openclaw plugins install "@tencent-weixin/openclaw-weixin"

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

# 第 3 步：重启 Gateway
openclaw gateway restart

# 第 4 步：扫码登录（见下一节）
openclaw channels login --channel openclaw-weixin

版本兼容速查

插件和 OpenClaw 的版本有对应关系，装错就会报错：

插件版本线	OpenClaw 版本	npm tag	安装命令
2.x（最新）	≥ 2026.3.22	latest	openclaw plugins install @tencent-weixin/openclaw-weixin
1.x（legacy）	≥ 2026.1.0 且 < 2026.3.22	legacy	openclaw plugins install @tencent-weixin/openclaw-weixin@legacy

---

扫码登录

这一步需要你在运行 Gateway 的机器上打开终端操作，因为要在终端里显示二维码。

openclaw channels login --channel openclaw-weixin

终端会打印一个二维码，同时给出一个备用的扫码链接。两种方式二选一：

1. 直接扫码：用手机微信扫终端里的二维码
2. 链接扫码：如果终端显示有问题（比如字体导致二维码变形），复制打印出来的链接在浏览器打开，再扫码

扫码注意事项

⚠️ 二维码有时效！大概 1-2 分钟就会过期。我第一次就是扫着扫去干别的了，回来二维码已经失效，又得重新来。建议准备好了再执行登录命令。

⚠️ 鸿蒙系统暂不支持。目前微信的 ClawBot 插件对鸿蒙版微信还没有适配，iOS 和 Android 需要更新到微信 8.0.70 以上版本。

⚠️ 关闭微信多开/分身工具。如果你用了微信多开或者分身助手，扫码可能会失败，先关掉再试。

登录成功后，插件会自动把 bot_token 保存在本地（~/.openclaw/ 目录下），下次重启 Gateway 不需要重新扫码。

验证连接

# 查看渠道状态
openclaw channels status

# 如果 openclaw-weixin 显示 OK，说明连接成功

---

访问控制：谁能跟你的 AI 聊天

默认情况下，不是所有人都能通过微信给你的 AI 发消息。新联系人需要审批：

# 查看待审批的联系人
openclaw pairing list openclaw-weixin

# 批准某个联系人
openclaw pairing approve openclaw-weixin <CODE>

<CODE> 就是 pairing list 输出里显示的配对码。审批通过后，这个联系人就可以直接在微信里跟你的 AI 聊天了。

如果你想开放给所有微信好友（不太推荐，容易被刷消息），可以在配置文件里调整 allowlist 策略：

{
  "channels": {
    "openclaw-weixin": {
      "allowFrom": ["*"]
    }
  }
}

更安全的做法是指定特定的微信 ID：

{
  "channels": {
    "openclaw-weixin": {
      "allowFrom": ["wxid_abc123", "wxid_def456"]
    }
  }
}

---

多账号支持

如果你有多个微信号想接入（比如一个工作号一个生活号），再跑一次登录命令就行：

openclaw channels login --channel openclaw-weixin

每次扫码会添加一个新的账号条目。查看已登录的账号：

cat ~/.openclaw/openclaw-weixin/accounts.json

多账号场景下，强烈建议开启会话隔离，否则不同微信号的消息可能会串：

openclaw config set session.dmScope per-account-channel-peer

这样不同微信号的私聊会话是完全独立的，互不干扰。

---

支持和不支持的功能

目前微信插件还在持续更新中，功能覆盖情况如下：

功能	支持状态	说明
私聊文字消息	✅	完整支持，流式输出
图片收发	✅	CDN 加密传输（AES-128-ECB）
文件收发	✅	支持常见文件格式
语音消息	✅	SILK 编码，自动转文字
视频消息	✅	CDN 加密传输
群聊	⏳	插件元数据暂未声明，后续版本开放
视频通话	❌	暂不支持
"正在输入"状态	✅	插件会自动发送 typing 状态

私聊场景基本够用了。日常信息查询、内容创作、技术问答、图片分析这些，微信里直接发消息就行。

---

进阶配置

自定义 BotAgent

每条出站消息会携带一个 bot_agent 字段（类似 HTTP 的 User-Agent），用于日志归因。默认值是 OpenClaw。

如需自定义，在 openclaw.json 中添加：

{
  "channels": {
    "openclaw-weixin": {
      "botAgent": "MyBot/1.2.0"
    }
  }
}

格式建议用 Name/Version 风格，多个 token 用空格分隔，总长度不要超过 256 字节。

配合 Web 控制面板使用

Gateway 启动后，浏览器打开 http://127.0.0.1:18789/ 就能看到 OpenClaw 的 Web 控制面板。在这里可以：

• 查看所有渠道的连接状态
• 直接在网页上跟 AI 对话
• 管理会话和配置
• 查看 Gateway 日志

如果你需要远程访问，建议通过 SSH 隧道或者 Tailscale，不要直接把 18789 端口暴露到公网。

模型切换

微信渠道默认使用你在 openclaw onboard 时配置的模型。如果想给微信单独配一个模型：

openclaw config set channels.openclaw-weixin.model "glm-5.1"
openclaw gateway restart

我的做法是日常用 GLM-5.1（便宜、延迟低），复杂任务切换到 Claude Opus 4.5。通过 Web 控制面板切模型最方便。

---

两种部署方案对比

除了本地部署，你也可以把 OpenClaw 跑在云服务器上。两种方案各有优劣：

维度	本地部署（macOS/Windows）	云服务器部署
成本	零（用自己的电脑）	腾讯云轻量 2C4G 约 30-50 元/月
稳定性	依赖电脑是否开机	7×24 小时运行
延迟	本地处理，几乎无延迟	取决于服务器地域
适用场景	个人日常使用	需要随时响应、团队共享
配置难度	简单	需要基础 Linux 知识
网络要求	直连即可	境外节点更稳定

我的选择是本地 macOS 部署，因为电脑基本不怎么关机，而且本地跑延迟最低。如果你需要 AI 全天候在线（比如做定时任务、监控告警），云服务器更合适。

---

我踩过的坑（按踩坑频率排序）

1. Gateway 反复重启（踩坑率最高）

装完插件后 Gateway 疯狂重启——这个问题十有八九是插件版本和 OpenClaw 版本不匹配导致的。解决方案：

# 先看当前版本
openclaw --version

# 更新 OpenClaw 到最新版
npm update -g openclaw

# 强制重装插件（匹配最新版本）
openclaw plugins install "@tencent-weixin/openclaw-weixin" --force

# 重启
openclaw gateway restart

如果还不行，查看详细日志定位问题：

openclaw gateway restart --verbose
# 或者
openclaw logs --follow

2. 插件安装了但不生效

检查插件是否启用：

openclaw plugins list

在输出里找到 openclaw-weixin 那行，看状态是不是 enabled。如果是 disabled，手动启用：

openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restart

3. 扫码后没反应

确认你的 Gateway 正在运行：

openclaw gateway status

如果 Gateway 挂了，扫码也不会生效。先启动 Gateway 再扫码。

另外检查一下网络——插件需要访问 ilinkai.weixin.qq.com，如果你在公司网络或者有防火墙，可能需要确认这个域名没被拦截。

4. 插件报 TypeScript 编译错误

如果看到类似 requires compiled runtime output for TypeScript entry 的错误，说明你装了个没编译好的版本。这是插件打包的问题，不是你的锅。等插件发新版或者暂时禁用：

openclaw config set plugins.entries.openclaw-weixin.enabled false
openclaw gateway restart

5. 找不到微信 ClawBot 插件入口

如果你在微信客户端的「设置 → 插件」里找不到 ClawBot，可能是以下原因：

• 微信版本太低：更新到最新版（≥ 8.0.70）
• 账号还在灰度覆盖范围外：耐心等 1-2 天，腾讯在分批推送
• 关闭微信重新打开再试

这个只影响通过微信客户端可视化配置的方案（WorkBuddy 桌面端方案），命令行方案不受影响。

6. Sidecar 进程导致重启循环

微信插件在监控 iLink API 时会启动一个 Sidecar 辅助进程。在某些系统（特别是用 systemd 管理的 Linux 服务器）上，子进程可能会误杀父 Gateway 进程，导致无限重启。这个问题在 OpenClaw 较新版本中已修复，确保你的 OpenClaw 版本足够新就行。

---

日常使用体验

接入之后，我在微信里打开自己的对话框（微信可以给自己发消息），直接发文字就能跟 AI 对话。发图片它会看图回复，发文件它能解析内容，发语音它自动转文字再处理。

几个我常用的场景：

• 快速问答：随手发一句"今天北京天气怎么样"，秒回
• 图片分析：拍个截图发过去，让它帮我分析错误信息
• 文档处理：发个 PDF 过去，让它总结要点
• 翻译：直接发外语文本，让它翻译
• 写代码：描述需求，它直接给你代码

跟之前用 Telegram 相比，微信的优势是——你不用专门装新 App，日常用的通讯工具里就能跟 AI 聊。劣势是没有群聊支持（暂时），也不能像 Telegram 那样用 inline keyboard 之类的高级功能。

对我来说最大的价值是：使用 AI 的门槛降到了零。不用切换 App，在微信里随手发一句就行。这种体验上的差异，用过就回不去了。

---

速查表

操作	命令
安装 OpenClaw	npm install -g openclaw@latest
初始化配置	openclaw onboard --install-daemon
查看 OpenClaw 版本	openclaw --version
启动 Gateway	openclaw gateway start
查看 Gateway 状态	openclaw gateway status
快捷安装微信插件	npx -y @tencent-weixin/openclaw-weixin-cli install
手动安装微信插件	openclaw plugins install "@tencent-weixin/openclaw-weixin"
安装旧版插件	openclaw plugins install "@tencent-weixin/openclaw-weixin@legacy"
扫码登录	openclaw channels login --channel openclaw-weixin
查看渠道状态	openclaw channels status
查看插件列表	openclaw plugins list
启用插件	openclaw config set plugins.entries.openclaw-weixin.enabled true
禁用插件	openclaw config set plugins.entries.openclaw-weixin.enabled false
查看待审批	openclaw pairing list openclaw-weixin
批准联系人	openclaw pairing approve openclaw-weixin <CODE>
设置会话隔离	openclaw config set session.dmScope per-account-channel-peer
重启 Gateway	openclaw gateway restart
查看详细日志	openclaw logs --follow
Web 控制面板	浏览器打开 http://127.0.0.1:18789/
卸载插件	openclaw plugins uninstall @tencent-weixin/openclaw-weixin

---

常见问题

Q：安装插件需要翻墙吗？
不需要。npm 包和微信 iLink API 都是直连的，不需要任何代理。不过如果你用国内网络，npm 有时候比较慢，可以换成淘宝镜像：npm config set registry https://registry.npmmirror.com/

Q：会不会被封号？
这个插件走的是腾讯官方的 iLink 协议，跟微信 PC 端登录是同一套授权机制。目前没有听说有封号案例。但毕竟是自动化操作，建议别太频繁发消息，正常使用完全没问题。

Q：一台电脑能挂几个微信号？
理论上可以挂多个，用多次 channels login 添加不同账号就行。建议设置会话隔离避免串消息。

Q：手机端微信需要保持登录吗？
跟 PC 端微信一样，扫码登录后手机端可以正常使用，不需要一直开着。但如果手机端退出登录，Bot 端的授权也会失效，需要重新扫码。

Q：鸿蒙系统的微信能用吗？
目前鸿蒙版微信还没有适配 ClawBot 插件，iOS 和 Android 需要更新到微信 8.0.70 以上版本。

Q：能用在群里吗？
当前插件版本（2.x）的元数据暂未声明群聊支持，后续版本预计会开放。如果你急需群聊功能，可以关注插件的 GitHub 仓库获取最新进展。

Q：Gateway 占用多少资源？
OpenClaw Gateway 本身很轻量，日常运行大概占用 100-200MB 内存，CPU 几乎可以忽略。主要的资源消耗在 AI 模型的 API 调用上，不过那是云端的事，不影响本地。

Q：卸载后微信会怎样？
卸载插件后，微信端不会有任何残留。之前通过 Bot 收发的消息还在微信聊天记录里，只是 Bot 不再回复了。

---

参考链接

• OpenClaw 官方文档 - 微信渠道：https://docs.openclaw.ai/zh-CN/channels/wechat
• 插件 npm 包：https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin
• OpenClaw GitHub：https://github.com/openclaw/openclaw
• OpenClaw 官网：https://openclaw.ai/
• iLink 协议解析：https://zeeklog.com/wei-xin-zhong-yu-kai-fang-guan-fang-bot-api-clawbot-cha-jian-shen-du-jie-xi-ai-kai-fa-zhe-de-xin-ji-yu-6
• OpenClaw 中文入门指南：https://blog.csdn.net/ChailangCompany/article/details/157739193