• 后端
• CLI
• MCP 服务
• 即时通讯
• RAG
• 人工智能
• AI 技能

Chatlog Alpha（chatlog_alpha）是一款微信数据库解密读取工具，内置 HTTP API 服务：在 TUI 中执行"启动 HTTP 服务"后，浏览器或脚本即可通过http://127.0.0.1:5030查询会话、历史消息、朋友圈、联系人，甚至直接执行只读 SQL。本手册按功能分类，给出全部核心 HTTP API 的接口地址、参数与调用示例，帮你把本地微信数据变成可编程的数据源。

一、启动服务与基础约定

在 TUI 中完成密钥提取与数据解密后，选择"启动 HTTP 服务"，默认监听0.0.0.0:5030（定义于 internal/chatlog/conf/server.go）。本机访问地址：

http://127.0.0.1:5030/

💡 若不希望局域网访问，可在配置中将监听地址改为127.0.0.1:5030。

两个全局约定：

• 输出格式：绝大多数/api/v1/*接口默认返回 YAML，追加format=json参数即返回 JSON（格式处理见 internal/chatlog/http/route.go 的writeByFormat）。
• 时间参数：time参数支持以下写法（解析逻辑见 pkg/util/time.go）：

也可用since/until传入 Unix 时间戳代替time。

二、接口总览

完整路由注册见 internal/chatlog/http/route.go 的initRouter：

三、会话与历史消息接口

1. 会话列表：GET /api/v1/sessions

获取最近会话列表，chat字段为显示名，username是后续接口需要的会话 ID。

curl "http://127.0.0.1:5030/api/v1/sessions?limit=10&format=json"

每条记录包含chat、username、is_group、chat_type（private/group）、summary（最后一条消息摘要）、timestamp等字段。

2. 历史消息：GET /api/v1/history

查询单个会话的历史记录，chat为必填参数。

curl "http://127.0.0.1:5030/api/v1/history?chat=wangwx&time=last-7d&limit=50&format=json"

返回体除消息数组外，还带chat、user_name、total_count等元信息；媒体消息会附带可直接访问的/image/...等链接。

3. 关键词搜索：GET /api/v1/search

跨会话搜索消息内容（区别于下面 db/search 的跨库搜索）。

curl "http://127.0.0.1:5030/api/v1/search?keyword=发票&time=last-30d&format=json"

4. 未读与增量消息：unread/new_messages

• GET /api/v1/unread?limit=20&filter=group：按unread_count > 0返回未读会话，filter可取private、group、official、folded。
• GET /api/v1/new_messages?limit=200：配合state参数（各会话上次时间戳的 JSON）实现增量拉取，响应中的new_state供下次请求使用——适合写轮询脚本。

5. 会话统计：GET /api/v1/stats

按会话聚合统计：总条数、收发比例、活跃天数、24 小时分布、群聊 Top10 发言人。

curl "http://127.0.0.1:5030/api/v1/stats?chat=项目群@chatroom&time=last-30d&format=json"

四、联系人与群聊接口

# 列出群成员并定位群主 curl "http://127.0.0.1:5030/api/v1/members?chat=1234567890@chatroom&format=json"

另有GET /api/v1/favorites?limit=50&fav_type=2&query=关键词可查询收藏（文本/图片/文章/名片/视频，fav_type分别为 1/2/5/19/20）。

五、朋友圈接口

朋友圈数据来自sns.db，共三个接口：

参数说明：

• sns_feed：limit（默认 20）、user（按作者名/昵称过滤）、time（时间范围）。
• sns_search：keyword（必填）、user、limit。
• sns_notifications：limit（默认 50）、include_read=true包含已读。

# 最近 30 天的朋友圈动态 curl "http://127.0.0.1:5030/api/v1/sns_feed?limit=20&time=last-30d&format=json" # 搜索包含"团建"的朋友圈 curl "http://127.0.0.1:5030/api/v1/sns_search?keyword=团建&format=json"

朋友圈条目包含timestamp、username（作者）、content（文案）、location、media_list（图片/视频地址）与article（图文）字段，media_list中的地址可直接在浏览器打开。

六、数据库浏览与 SQL 查询接口

这一组接口让你像浏览普通 SQLite 库一样操作解密后的微信数据库。数据库按业务分组（group），如message、session、sns、favorite。

1. 列出数据库：GET /api/v1/db

返回所有已解密数据库文件的分组清单，是后续接口的"目录"。

2. 跨库全局搜索：GET /api/v1/db/search

3. 表结构浏览：GET /api/v1/db/tables

curl "http://127.0.0.1:5030/api/v1/db/tables?group=message&file=message_0.db"

group与file均从GET /api/v1/db的结果中取得。

4. 表数据分页 / 导出：GET /api/v1/db/data

5. 只读 SQL：GET /api/v1/db/query

对指定库执行 SQL 查询，这是最灵活的接口：

curl -G "http://127.0.0.1:5030/api/v1/db/query" \ --data-urlencode "group=message" \ --data-urlencode "file=message_0.db" \ --data-urlencode "sql=SELECT count(*) AS total FROM MSG"

同样支持format=csv/format=xlsx导出查询结果。

⚠️ 接口面向本地数据浏览设计，请只执行SELECT类只读语句，并妥善保管解密后的数据库与密钥文件（all_keys.json以 0600 权限写入）。

七、媒体资源访问

历史消息中的媒体 key 可直接拼接为下载地址（路由定义见 internal/chatlog/http/route.go 的initMediaRouter）：

例如/api/v1/history返回的图片消息带md5字段后，浏览器访问http://127.0.0.1:5030/image/<md5>即可看到原图。

八、用 CLI 调用 HTTP API

不想开浏览器？项目内置 HTTP CLI，接口别名一览见 skills/chatlog-http-cli/SKILL.md：

# 查看所有可调用接口 chatlog http list # 查询会话历史（等价于 GET /api/v1/history） chatlog http call --endpoint history \ --query chat=项目群 --query limit=100 --query format=json # 跨库深度搜索 chatlog http call --endpoint db/search \ --query keyword=项目 --query mode=deep --query limit=100 # 只读 SQL 查询 chatlog http call --path /api/v1/db/query \ --query group=message --query file=message_0.db \ --query 'sql=SELECT count(*) AS total FROM MSG'

--endpoint使用别名，--path可直接指定原始路径，--query key=value可重复传入多个参数，另有--addr（默认127.0.0.1:5030）、--timeout、--output等常用开关。

九、进阶能力速览

除核心查询外，服务还内置若干可选模块（路由均在 internal/chatlog/http/route.go 中注册）：

• 语义检索/api/v1/semantic/*：向量检索、RAG 问答（支持 SSE 流式）、主题/画像分析、索引重建；
• 时间知识图谱/api/v1/graph/*：时间线、可视化与图谱问答；
• 消息推送/api/v1/hook/*：配置关键词与转发范围后，可把全部或指定消息实时推送到 clawbot（Hermes Weixin / QQ）；
• 发信调试/api/v1/send-debug/*：仅接受本机回环请求的 macOS 文本/图片发送调试链路；
• MCP 服务：/mcp、/sse、/message三个入口，可直接接入 Hermes 等 MCP 客户端，并提供wx_semantic_search等工具。

十、常见参数速查表

📌 排障提示：接口返回数据库相关错误时，先确认 TUI 已完成"解密数据"步骤；页面打不开时检查5030端口占用情况。

掌握以上接口后，你就可以用脚本自动汇总群消息、归档朋友圈、批量导出数据库，甚至接入 MCP 让 AI 直接检索你的微信数据。接口路由实现集中在 internal/chatlog/http/route.go 与 internal/chatlog/http/service.go，需要深入了解某个接口的返回结构时，可直接对照源码阅读。

• 后端
• CLI
• MCP 服务
• 即时通讯
• RAG
• 人工智能
• AI 技能