跳转到内容

架构设计

宿主机设备 HTTP HTTP + 事件流 HTTP 微信底层协议 wx CLI OpenClaw 插件 其他智能体与应用 微信服务端 wx serve 微信 Profile 目录聊天记录、联系人、媒体 Daemon 数据目录凭据、任务队列、事件日志

wx serve 像官方桌面端一样直接对接微信底层网络协议。无需在后台运行官方微信应用、图形桌面或任何浏览器实例。

微信 Profile 目录始终是数据主存储。 聊天历史、联系人和媒体资源全部以 Linux 版微信原生兼容的加密格式保存,无论是 Daemon 初始新建的 Profile,还是通过 --official 挂载的现有官方目录。Daemon 接收或发出的消息会直接写入其中,效果等同于官方客户端亲自执行的操作。

Daemon 独立保存自己的数据: 登录凭据、排队中的发送与下载、事件日志,以及 Profile 中没有对应位置的数据。

所有客户端面向同一套 HTTP API。 CLI 仅仅是该 API 的轻量命令行封装。OpenClaw 插件通过监听 SSE 事件流并调用相同的 API 路由运行,任何第三方智能体插件或应用程序均可以此方式接入。参考 HTTP API。

Daemon 内部模块组成

核心组件职责分工
账号 Worker (Account worker)每个账号独立 Worker:管理与微信的长连接、维持登录状态,并协调账号变更与恢复
同步引擎 (Sync)通过服务端推送长连接实时接收新消息;若连接掉线则平滑降级为轮询
Profile 读写器 (Profile reader/writer)通过小型一致性快照池读取历史;为受支持的数据库结构维持单一写入者
任务队列 (Job queue)异步调度发送、下载、撤回与已读回执任务,支持跨进程重启状态持久化恢复
事件日志 (Event log)严格记录所有已提交的数据变更,供客户端重放追溯错过的增量事件
HTTP 服务端 (HTTP server)提供 /v1 REST 接口,校验令牌权限,提供 SSE 事件流长连接

对于由 Daemon 拥有且使用 SQLite WAL 日志模式的 Profile,Worker 会短暂暂停写入,以捕获每个请求的数据库及事件位置快照。随后在请求读取与格式化结果期间释放写入锁。单个账号最多可并发执行 4 个读取操作,整个 Daemon 跨账号最多并发执行 8 个。使用其他日志模式的 Profile 则继续维持串行读取;Daemon 不会主动更改其数据库日志模式。

下载操作采用独立的并发限制:每个账号最多 2 个并发,整个 Daemon 最多 4 个并发。网络等待期间会释放账号的写入锁,并在保存结果前重新检查登录状态与任务状态。表情操作、联系人与群聊查询、群聊变更及撤回操作在网络等待期间同样会释放写入锁。冲突的操作仍保留其顺序保护;在保存结果前,登出与凭据检查依然生效。

已添加表情包列表与已建立索引的消息媒体使用一致的读取快照。发现并登记缺失的媒体仍使用写入锁。待处理的媒体会重新检查官方 Profile 中可能已存在的文件。

同一 Daemon 的所有客户端共享一个短期的表情元数据缓存。它在内存中最多保留 64 个目录、详情和说明响应,单个响应不超过 128 KiB,有效期 60 秒,并会合并对同一元数据的并发请求。重启后缓存清空。缓存条目按账号和已通过身份验证的会话分隔;登出会移除该账号的条目。成员关系与媒体可用性从 Profile 和已有的媒体记录中读取,而非来自此缓存。

查看 Rust Crate 架构 了解各包划分与依赖关系,直接调用底层库请参考 Rust 开发库。