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

Chatlog Alpha 是一款面向微信 4.x 的本地聊天数据读取、查询与分析开源工具，支持微信数据库解密、跨库全局搜索、仪表盘浏览，并提供 MCP 服务、HTTP 服务以及通过微信 clawbot 接口实时转发消息的能力。本文是一份完整的全平台部署清单，带你从零完成 macOS 与 Windows 的下载安装、密钥提取、服务启动，并附上常见问题排查清单。

一、Chatlog Alpha 是什么？先认识 5 大核心能力

在动手安装前，先了解它会为你做什么（详见 README.md）：

• 🗂️终端交互界面（TUI）：一步步引导你完成账号选择、密钥提取、数据解密
• 🌐Web 管理与数据浏览界面：会话、历史消息、联系人、群聊、媒体浏览
• 🔌HTTP API 与 MCP 服务：可接入 Hermes Agent 等 AI 工具
• 🔍跨数据库搜索 + 仪表盘：群聊对比、消息趋势、发言人排行
• 🤖关键词事件与 Hermes Weixin / QQ 推送：支持把全部或指定消息实时转发到 clawbot

数据库解密、查询和缓存默认在本机执行，数据不出内网；只有配置远程模型（如 GLM、DeepSeek）时，选中的检索文本才会发送到对应模型服务。

二、平台兼容性速查表：你的系统能不能跑？

结论：macOS 体验最完整；Windows 可用但密钥提取仍在实验阶段，微信版本更新后可能需要等待适配。

三、下载前 3 项准备清单

• 安装并登录微信桌面版，且能正常自动登录
• 确认 CPU 架构：
  • macOS 执行uname -m：输出arm64下载darwin_arm64，输出x86_64下载darwin_amd64
  • Windows 优先选windows_amd64（Chatlog 与微信架构需匹配）
• macOS 额外准备：Python 3 环境（用于 Frida）；如需手机历史记录，可先在手机微信我 → 设置 → 通用 → 聊天记录迁移与备份中迁移

四、如何下载正确的安装包？

从项目仓库的 Latest Build 发布页下载与你的平台匹配的压缩包，文件名格式如下：

💡推荐下载.zip压缩包：包内chatlog-darwin-arm64已保留755执行权限，解压即可运行，且同时包含README.md、LICENSE和 macOS 的start-chatlog.command启动脚本。

五、macOS 安装步骤（含 SIP 与 Frida 配置）

第 1 步：检查 SIP 系统保护

macOS 的数据库密钥仅通过 Frida 获取，而当前微信版本在 SIP 开启时会拒绝 Frida 附加：

csrutil status

• 显示disabled：直接进入下一步 ✅
• 显示enabled：需进入macOS 恢复模式，在终端执行csrutil disable后重启，再次确认显示disabled（⚠️ 会降低系统安全性，提取完成后可执行csrutil enable恢复）

第 2 步：安装 Frida 工具

使用当前登录用户安装，不要使用sudo pip：

python3 --version python3 -m pip install --user -U frida-tools python3 -c "import frida; print(frida.__version__)"

最后一条命令能打印版本号即安装成功。发布版二进制已内嵌 Frida 脚本（如 scripts/wechat_key_frida.py），无需手动指定。

第 3 步：解压并启动

unzip chatlog_*_darwin_arm64.zip chmod +x chatlog-darwin-arm64 ./chatlog-darwin-arm64

也可以更简单：在 Finder 中双击start-chatlog.command，系统会自动打开终端、定位对应架构的二进制、恢复执行权限并清理下载隔离标记。首次启动如出现系统确认窗口，请在 Finder 中右键该文件选择“打开”。

六、Windows 安装步骤（3 个注意点）

解压后以管理员身份打开终端并运行：

.\chatlog-windows-amd64.exe

⚠️ 三个注意点：

1. 先启动并登录微信，再运行 Chatlog（密钥来自微信进程内存扫描）
2. 建议以管理员身份运行，否则可能读取不到进程内存
3. windows/arm64为非 CGO 构建，语音转 MP3 等依赖 CGO 的能力会受限

七、首次运行：6 步完成微信数据库解密

启动 TUI 后按界面提示操作（密钥流程对应 cmd/chatlog/cmd_key.go 的key子命令逻辑）：

1. 切换账号：确认选择了正确的微信账号
2. 重启并获取数据库密钥：TUI 显示 6 步进度，期间微信会自动重启
3. 等待微信重新启动并完成登录
4. 获取图片密钥：仅在需要查看加密媒体时执行；若提示需要验证样本，优先在微信朋友圈中打开一张图片
5. 解密数据：建立本地工作目录
6. 启动 HTTP 服务：浏览器访问http://127.0.0.1:5030/

密钥流程全部通过时会看到：

✓ 1/6 检查 Frida 环境 ✓ 2/6 重启并启动微信 ✓ 3/6 挂载进程并安装 Hook ✓ 4/6 短时收集各数据库候选密钥 ✓ 5/6 卸载 Hook 并断开会话 ✓ 6/6 逐库验证密钥并保存映射

启动后你就可以在 Web 界面浏览会话、历史消息和媒体，也可以用 CLI 直接调用接口：

chatlog http list chatlog http call --endpoint history --query chat=<会话ID> --query limit=100 --query format=json

更多接口别名与参数见 skills/chatlog-http-cli/SKILL.md，命令入口实现在 cmd/chatlog/cmd_http.go。

八、源码构建（可选）：3 条命令本地编译

如需从源码构建（环境要求：Go 1.25+、Git、支持 CGO 的 C 编译器，见 go.mod）：

git clone https://gitcode.com/gh_mirrors/ch/chatlog_alpha cd chatlog_alpha CGO_ENABLED=1 go build -trimpath -o bin/chatlog .

也可以使用仓库自带的 Makefile 一键构建（含 lint、测试）：

make build

九、常见问题排查清单

十、数据安全与关键文件位置

🔐安全提醒：请仅处理你有权访问的本地数据，妥善保管生成的密钥、缓存与解密结果。

总结

至此你已完成 Chatlog Alpha 在 macOS 或 Windows 上的完整部署：下载匹配架构的安装包 → 配置 SIP/Frida（macOS）或管理员权限（Windows）→ 按 TUI 6 步完成密钥提取与数据解密 → 启动 HTTP 服务与 Web 仪表盘。后续还可以继续探索它的语义检索、时间知识图谱和 Hermes clawbot 消息推送能力，把微信聊天记录变成可搜索、可分析、可自动转发的数据资产。

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