微信 Clawbot 与本地 OpenClaw 连接架构详解

黑带架构湿

556人浏览 · 2026-03-27 10:10:58

黑带架构湿 · 2026-03-27 10:10:58 发布

一、整体连接架构

二、完整消息交互流程

2.1 入站消息流程（微信 → OpenClaw）

步骤	发送方	接收方	说明
1	微信用户	微信服务器	用户发送文本/图片消息
2	微信服务器	iLink API	消息推送到 iLink Bot 网关
3	OpenClaw	iLink API	monitor.ts 发起 GET /getupdates 长轮询 (timeout: 35s)
4	iLink API	OpenClaw	有新消息时立即返回 msgs 数组
5	OpenClaw	OpenClaw	processOneMessage 标准化为 MsgContext，记录 context_token
6	OpenClaw	OpenClaw	dispatchReply 传递给 AI 核心处理
7	OpenClaw	OpenClaw	AI 生成回复内容

关键代码位置：

monitor.ts:monitorWeixinProvider() — 长轮询主循环
inbound.ts:weixinMessageToMsgContext() — 消息标准化
process-message.ts:processOneMessage() — 消息处理入口

2.2 出站消息流程（OpenClaw → 微信）

步骤	发送方	接收方	说明
1	OpenClaw AI	send.ts	AI 生成回复文本/媒体
2	send.ts	send.ts	buildSendMessageReq 构建消息体
3	send.ts	iLink API	POST /sendmessage，携带 to_user_id 和 context_token
4	iLink API	微信服务器	路由到微信服务器
5	微信服务器	微信用户	用户收到回复消息

关键代码位置：

send.ts:sendMessageWeixin() — 发送文本消息
send.ts:sendImageMessageWeixin() — 发送图片（需先上传 CDN）
api/api.ts:sendMessage() — 底层 API 调用

三、核心机制说明

3.1 长轮询 (Long-Poll) 机制

问题：openclaw gateway 监听的是 127.0.0.1:18789（本地），微信服务器无法直接访问。

解决方案：反向拉取模式

// monitor.ts 中的长轮询循环
while (!abortSignal?.aborted) {
  const resp = await getUpdates({
    baseUrl:        // 微信 iLink API 公网地址
    token:          // Bot Token 认证
    get_updates_buf: // 增量同步游标
    timeoutMs: 35000, // 长轮询超时 (35 秒)
  });

  // 服务器会"持有"这个请求，直到：
  // 1. 有新消息到达 → 立即返回
  // 2. 超时 (35s) → 返回空响应，客户端重试
}

流程说明：

本地 monitor.ts 每 35 秒向微信 iLink API 发起一次 getUpdates 请求
微信服务器”持有”这个请求，不立即返回
当用户发送消息时，微信服务器立即响应，返回消息列表
如果没有消息，35 秒后返回空响应，客户端立即重试

本质：不是”推送”，而是”高频拉取 + 服务器延迟响应”

3.2 Context Token 机制（会话追踪）

问题：微信消息是单向的，如何确保回复发给正确的用户？

解决方案：context_token 双向传递

方向	动作	说明
入站	微信发送消息携带 context_token	每个消息都有唯一的上下文标识
入站	OpenClaw 提取并缓存 token	setContextToken(accountId, userId, token)
入站	持久化到状态文件	~/.openclaw/state/openclaw-weixin/accounts/
出站	OpenClaw 从缓存读取 token	getContextToken(accountId, userId)
出站	发送回复时附带相同 token	确保消息路由到正确的会话

代码位置：

inbound.ts:setContextToken() / getContextToken() — Token 缓存
send.ts:sendMessageWeixin() — 发送时附带 token

3.3 认证与路由

组件	地址	用途
iLink API 网关	https://api.ilink.weixin.qq.com/ (默认)	所有 API 请求的目标地址
openclaw gateway	127.0.0.1:18789 (本地)	OpenClaw 内部通信，不直接接收微信消息
Bot Token	扫码登录后获得	每次 API 请求的 Authorization: Bearer xxx 头

重要说明：

微信消息不会直接发送到 127.0.0.1:18789，而是：

微信服务器存储消息
本地 monitor.ts 主动拉取 (getUpdates)
消息在插件内部处理后，通过 OpenClaw 框架传递到 AI

3.4 媒体文件传输（加密 CDN）

图片/视频/文件发送流程：

步骤	操作	说明
1	本地文件	/tmp/img.png
2	POST 获取上传 URL	向 getUploadUrl 申请预签名 URL
3	PUT 上传文件	上传到微信 CDN 存储
4	返回 filekey + aeskey + 下载参数	CDN 返回加密文件信息
5	sendMessage 携带 encrypt_query_param	发送消息引用 CDN 链接

关键点：

文件在 CDN 上是加密存储的 (AES-128-ECB)
下载时需要 encrypt_query_param + aes_key
接收方微信客户端自动解密

四、配置与状态管理

4.1 账号数据存储位置

文件类型	路径	用途
账号凭证	~/.openclaw/state/openclaw-weixin/accounts/.json	存储 token, baseUrl, userId
Context Token 缓存	~/.openclaw/state/openclaw-weixin/accounts/.context-tokens.json	每个用户的会话 token
长轮询同步游标	~/.openclaw/state/openclaw-weixin/sync/.getupdates.buf	增量同步用
日志文件	~/.openclaw/logs/openclaw-weixin/.log	运行日志

4.2 典型配置命令

# 1. 微信扫码登录（获取 token）
openclaw channels login --channel openclaw-weixin

# 2. 启动网关（开始长轮询）
openclaw gateway --port 18789 --verbose

# 3. 查看账号状态
openclaw channels status --channel openclaw-weixin

# 4. 查看日志
tail -f ~/.openclaw/logs/openclaw-weixin/<accountId>.log

五、常见问题排查

问题	可能原因	排查方法
收不到微信消息	长轮询未启动	检查 openclaw gateway 是否运行
消息发送失败	context_token 丢失	检查 ~/.openclaw/state/openclaw-weixin/accounts/*.context-tokens.json
会话过期	Bot Token 失效	重新扫码登录，检查日志中的 SESSION_EXPIRED_ERRCODE
媒体上传失败	CDN 上传 URL 过期	检查网络，重试上传

六、总结

核心要点

要点	说明
不是推送，是拉取	微信不会主动连接本地 gateway，而是本地 monitor.ts 不断长轮询 getUpdates
context_token 是会话关键	每次 inbound 消息都携带，outbound 必须原样返回
gateway 127.0.0.1 只用于内部	微信消息不经过这个端口，它在插件内部处理后直接交给 OpenClaw 核心
媒体文件走加密 CDN	先上传获取 filekey + aeskey，发送时引用 CDN 链接

架构优势

✅ OpenClaw自身无需公网 IP / 内网穿透
✅ 会话状态持久化（重启不丢失）
✅ 增量同步（不重复处理消息）
✅ 安全的媒体传输（AES 加密）

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

告别扫描文档处理烦恼：ScanTailor Advanced的智能文档优化解决方案

ScanTailor Advanced是一款专业的扫描文档后期处理工具，专为解决老旧文档数字化中的各种问题而设计。通过智能内容识别、批量处理和多线程优化，它能将倾斜、模糊、杂乱的扫描文档转化为整洁的电子文件，显著提升文档数字化效率。## 文档数字化的常见痛点与解决方案### 页面歪斜校正：智能算法自动修正传统扫描文档经常出现页面歪斜问题，手动调整每页耗时耗力。ScanTailor Adv

AI Agent技术社区

SeedVR2终极指南：如何用单步扩散模型实现专业级视频修复

还在为老旧视频的模糊画质而烦恼吗？面对抖动严重的监控录像或褪色的家庭影像，你是否曾希望有一种简单高效的修复方案？SeedVR2正是为解决这些痛点而生的一站式视频修复工具。作为字节跳动推出的先进视频修复模型，它能够在单步推理中实现专业级的视频质量提升，彻底改变了传统视频修复的工作流程。## 核心价值：为什么选择SeedVR2进行视频修复？**传统视频修复的三大瓶颈**：1. **计算成本高

AI Agent技术社区

终极指南：如何用Python自动化工具告别大麦抢票焦虑，轻松获取心仪演出门票

还记得那些让你心跳加速的抢票时刻吗？热门演唱会开票瞬间，你手忙脚乱地刷新页面，却眼睁睁看着"立即购买"按钮变灰，票在几秒内售罄。这种"拼手速"的抢票时代已经过去，现在有了基于Python开发的大麦自动抢票工具，让你告别手速焦虑，轻松获取周杰伦、五月天、周深等热门演出的门票。## 🔥 你的抢票痛点，我们都有解决方案### 场景一：热门演唱会一票难求"周杰伦演唱会开票3秒售罄，我连页面都没