OpenClaw 微信接入指南 | 含云服务器+本地两种部署方式

OpenClaw 微信接入指南

一、插件概述

OpenClaw 微信插件（openclaw-weixin）是 OpenClaw 官方支持的微信接入方案，支持通过扫码授权登录，让 AI 与微信用户直接对话。

核心特点：

扫码登录，无需密码，安全可靠
支持多个微信账号同时在线
支持文本、图片、文件、语音、视频等多种消息类型
支持会话上下文隔离

前置要求：

OpenClaw Gateway 已运行
微信账号已实名认证（接口要求）

二、部署方式选择

接入微信有两种部署方式，可根据是否需要24小时在线来选择：

方式	适用场景	优点	缺点
云服务器部署	需要24小时接收消息、长时间运行	关电脑也能用，消息不漏	需要自备服务器
本地电脑部署	日常使用、个人尝鲜	零成本，快速上手	电脑关机则断连

两种方式的安装和扫码登录完全相同，区别仅在于 OpenClaw 运行的环境不同。

三、云服务器部署（推荐，24小时在线）

适合需要 AI 全天候响应消息的用户，例如运营机器人、个人助手等。

3.1 购买并初始化云服务器

推荐配置：

地域：国内服务器（微信接口延迟低）
系统：Ubuntu 22.04 LTS
规格：2核4G 起
网络：固定公网 IP，带宽 ≥ 5Mbps

3.2 安装 OpenClaw

# SSH 登录服务器后，一键安装 OpenClaw
curl -sL https://openclaw.ai/install.sh | sh

3.3 启动 Gateway

# 前台运行（测试用）
openclaw gateway

# 后台运行（生产用）
openclaw gateway install && openclaw gateway start

3.4 安装微信插件

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

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

3.5 扫码登录（关键步骤）

openclaw channels login --channel openclaw-weixin

扫码前请注意：

终端需要支持 UTF-8 字符（推荐使用 FinalShell、Mobaxterm 等支持 UTF-8 的 SSH 客户端）
国内服务器若二维码显示乱码，需确保 SSH 客户端字符编码为 UTF-8
若终端不支持显示二维码，可通过跳板机或开启 Tmate 远程查看

扫码后：

用微信扫码 → 确认授权
登录凭证自动保存到 ~/.openclaw/
凭证长期有效，定期重新扫码可保持活跃

3.6 验证运行

# 查看渠道状态
openclaw channels list

# 查看 Gateway 状态
openclaw gateway status

3.7 让 Gateway 开机自启

openclaw gateway install

服务器重启后 Gateway 自动启动，微信账号保持在线。

四、本地电脑部署（快速尝鲜）

适合本地开发测试、个人日常使用。

4.1 安装 OpenClaw

Mac/Linux：

curl -sL https://openclaw.ai/install.sh | sh

Windows：

# 使用 WSL2
wsl --install

4.2 启动 Gateway

openclaw gateway

4.3 安装插件

openclaw plugins install"@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true

4.4 扫码登录

openclaw channels login --channel openclaw-weixin

终端会显示二维码，用微信扫码授权即可。

4.5 重启生效

openclaw gateway restart

五、扫码登录详解

扫码是微信授权的核心步骤，所有部署方式都要经过这一步：

终端执行登录命令
    ↓
终端显示二维码（ASCII 字符或图片）
    ↓
用微信扫码（需要实名认证的账号）
    ↓
手机端确认授权
    ↓
登录凭证自动保存，完成

扫码失败常见原因：

微信账号未实名 → 去微信完成实名认证
服务器在国外 → 微信接口有地域限制，建议用国内服务器
频繁切换登录地 → 被微信安全拦截，换常用设备扫码

保持长期有效：

凭证通常长期有效，无需每天重扫
建议每隔1-2周重新扫码一次保持活跃
多账号登录：每次 login 命令扫码添加新账号

六、多账号支持

微信插件支持多个微信账号同时在线：

# 登录第2个微信账号
openclaw channels login --channel openclaw-weixin

# 查看已登录账号
openclaw channels list

适用场景：

个人号 + 工作号分开
不同业务线用不同账号

七、会话上下文隔离

默认所有渠道共享同一个 AI 上下文，微信消息会互相影响。开启隔离：

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

效果：每个「微信账号 + 联系人」拥有独立 AI 记忆，互不干扰。

八、消息类型支持

消息类型	接收	发送
文本消息	✅	✅
图片	✅	✅
文件	✅	✅
语音	✅	✅
视频	✅	✅
引用消息	✅	—

九、开发者 API 协议

若需对接自建后端，实现以下 HTTP JSON API 接口：

通用请求头：

Header	说明
AuthorizationType	固定值 ilink_bot_token
Authorization	Bearer <token>（扫码登录后获取）
X-WECHAT-UIN	Base64 编码的随机 uint32

核心接口

接口	路径	说明
getUpdates	getupdates	长轮询获取新消息
sendMessage	sendmessage	发送消息（文本/图片/视频/文件）
getUploadUrl	getuploadurl	获取 CDN 上传预签名 URL
getConfig	getconfig	获取账号配置（typing ticket 等）
sendTyping	sendtyping	发送/取消「正在输入」状态

sendMessage 示例

POST /sendmessage
{
"msg": {
"to_user_id": "<目标用户ID>",
"context_token": "<会话上下文token>",
"item_list": [
      { "type": 1, "text_item": { "text": "你好！" } }
    ]
  }
}

消息类型：1=文本，2=图片，3=语音，4=文件，5=视频

十、禁用微信渠道

openclawconfigsetplugins.entries.openclaw-weixin.enabledfalse
openclawgatewayrestart

十一、相关资源

官方文档：https://docs.openclaw.ai/channels
GitHub：https://github.com/tencent-weixin/openclaw-weixin
一键安装：npx -y @tencent-weixin/openclaw-weixin-cli install

安装成功后截图

后续将分享微信openclaw使用体验，敬请期待~~~