wx-cli REST API 完整参考：用 8 个端点搭建你的本地微信数据服务

wx-cli 是一个运行在 macOS 上的微信数据库解密与查询工具，它的wx-cli server run命令可以把本机微信数据变成一个标准的本地 REST API 服务：默认监听127.0.0.1:9100，提供 8 个/api/v1/*端点，覆盖会话、联系人、消息、时间线、媒体、全文搜索和 SSE 实时订阅。数据不出本机，个人助理、自动化脚本和多个 Agent 都能共享同一个服务实例。

1 分钟启动：最快配置方法

前提是已经完成密钥提取和解密（wx-cli key extract+wx-cli decrypt）。启动服务只需一条命令：

wx-cli server run

常用参数：

远程访问示例：

wx-cli server run --host 0.0.0.0 --token mysecret wx-cli server status # 查看状态 wx-cli server stop # 停止服务

⚠️ 安全提示：--host不是 loopback 地址而不带--token时，服务会直接拒绝启动（见 serve/mod.rs）。

8 个端点速查表

路由定义集中在 routes.rs，全部为 GET 请求：

统一响应结构与鉴权

所有 JSON 查询端点返回同一套信封结构（定义见 output.rs）：

{ "items": [ ... ], "paging": { "limit": 20, "offset": 0, "returned": 20, "has_more": true, "total": 342 }, "stats": { "scanned": 500, "skipped": 0, "elapsed_ms": 12 } }

• limit默认 20，可用limit/offset翻页；
• 大多数列表端点支持order=asc|desc（默认desc）和show_hidden=1（忽略联系人隐藏规则）。

鉴权：配置了--token后，所有请求需携带Authorization: Bearer <token>头，否则返回 401（实现见 auth.rs）。本机不带 token 启动时无需鉴权。

逐个端点详解

1. GET /api/v1/health — 健康检查

curl http://127.0.0.1:9100/api/v1/health

返回ready（服务是否就绪）、worker_id、cli_version和current_account（当前账号 wxid 与昵称）。ready=false表示桥接层仍在初始化，SSE 端点此时会返回 503。

2. GET /api/v1/sessions — 会话列表

curl "http://127.0.0.1:9100/api/v1/sessions?limit=10"

返回最近会话，含summary（最后一条消息摘要）、last_msg_type、sort_timestamp等字段；本地数据库有记录时还会带上avatar_url头像。参数：limit、offset、order、show_hidden。

3. GET /api/v1/contacts — 联系人搜索

curl "http://127.0.0.1:9100/api/v1/contacts?search=张三&limit=10"

search参数支持按昵称、备注等模糊过滤，返回 wxid、显示名、头像等信息（实现见 handlers.rs）。

4. GET /api/v1/messages — 单会话消息查询

最灵活的端点，contact支持传 wxid、昵称或备注名（自动解析）：

curl "http://127.0.0.1:9100/api/v1/messages?contact=张三&limit=20&type=text"

参数分两类，不可混用：

• 时间范围模式：since/until（Unix 秒）、type（消息类型）、offset翻页；
• 锚点模式：三选一 ——around_sort_seq、around_server_id、after_sort_seq，其中around_*可搭配context=N表示锚点消息前后各取 N 条。

约束（违反会返回 400）：

• 三个锚点参数互斥；
• 锚点模式不能与since/until同时使用；
• 锚点模式下offset必须为 0。

5. GET /api/v1/timeline — 跨会话时间线

一次请求读取时间范围内所有会话的消息，是 Agent 记忆补全、日报生成、归档批处理的关键端点，避免逐会话调用（实现见 handlers.rs）：

curl "http://127.0.0.1:9100/api/v1/timeline?since=1750000000&until=1750086400&limit=100"

要求since和until同时提供且since <= until，返回的每条消息带有talker、talker_display_name、direction（inbound/outgoing）和snippet摘要，可按order与type过滤、limit/offset翻页。

6. GET /api/v1/media — 媒体文件下载

按消息定位取回图片、语音、视频或文件（实现见 media.rs）：

# 语音，转成 mp3 curl -o voice.mp3 "http://127.0.0.1:9100/api/v1/media?server_id=123456&talker=张三&format=mp3" # 图片 curl -o img.jpg "http://127.0.0.1:9100/api/v1/media?server_id=123456&talker=张三"

• server_id与talker均必填，值可从 messages 查询结果中直接取；
• format仅语音有效：ogg（默认）或mp3（需本机安装 ffmpeg）；
• 图片响应带X-Wechat-Media-Quality: full|thumbnail头，标明返回的是完整图还是缩略图，服务始终优先返回本机已下载的高清原图。

7. GET /api/v1/search — 全文搜索

curl "http://127.0.0.1:9100/api/v1/search?q=周末爬山&limit=20"

优先走独立连接的 SQLite FTS 全文索引（不阻塞主库查询），失败时自动降级为逐会话扫描（实现见 handlers.rs）。stats.elapsed_ms字段可用于观察两种路径的性能差异。

8. GET /api/v1/events — SSE 实时订阅

长连接持续推送新消息，事件类型定义见 event.rs：

curl -N http://127.0.0.1:9100/api/v1/events

连接在服务未就绪时返回 503；客户端断线后重连即可，服务端通过增量游标补齐事件。

错误处理：HTTP 状态码对照

错误统一以{"error": "..."}返回，映射关系定义在 error.rs：

三个实用组合场景

1. 给 Agent 建长期记忆：定时用/timeline拉取过去一小时的跨会话消息 → 汇总生成日报/待办；
2. 关键词触发工作流：常驻连接/events，收到message事件后匹配关键词，命中则触发提醒；
3. 聊天知识库前端：/search提供搜索框，/messages提供会话视图，/media直接出图出语音，无需导出。

💡 提示：wx-cli的查询命令（sessions、query、search等）检测到本机server run在跑时会自动复用 REST API，可用--no-server强制本地查询、--server-only强制走服务。

延伸阅读

• 路由与中间件：routes.rs
• 各端点处理逻辑：handlers.rs
• 服务启动流程：mod.rs
• 服务端参数定义（--token、--poll-ms等）：server/types.rs
• 服务运行时状态上报：server/manager.rs
• 实时消息监控模块：wx-monitor

至此，8 个端点就构成了一整套完整的本地微信数据服务：历史数据靠sessions/contacts/messages/search/media，批量处理靠timeline，实时能力靠events，health兜底监控。一条wx-cli server run启动后，你的自动化程序就可以像访问任何标准 API 一样访问自己的微信数据了。