Wechat Log

__图片CDN配置

聊天记录工具，帮助大家轻松使用自己的聊天数据，将chatlog发扬光大

Feature

• 从本地数据库文件中获取聊天数据
• 支持 Windows / macOS 系统，兼容微信 3.x / 4.x 版本
• 支持获取数据与图片密钥 (Windows < 4.0.3.36 / macOS < 4.0.3.80)
• 支持图片、语音等多媒体数据解密，支持 wxgf 格式解析
• 支持自动解密数据库，并提供新消息 Webhook 回调
• 提供 Terminal UI 界面，同时支持命令行工具和 Docker 镜像部署
• 提供 HTTP API 服务，可轻松查询聊天记录、联系人、群聊、最近会话等信息
• 支持 MCP Streamable HTTP 协议，可与 AI 助手无缝集成
• 支持多账号管理，可在不同账号间切换

Quick Start

基本步骤

1. 安装 Chatlog：下载预编译版本 或 使用 Go 安装
2. 运行程序：执行 chatlog 启动 Terminal UI 界面
3. 解密数据：选择 解密数据 菜单项
4. 开启 HTTP 服务：选择 开启 HTTP 服务 菜单项
5. 访问数据：通过 HTTP API 或 MCP 集成 访问聊天记录

💡 提示: 如果电脑端微信聊天记录不全，可以从手机端迁移数据

常见问题快速解决

• macOS 用户：获取密钥前需临时关闭 SIP
• Windows 用户：遇到界面显示问题请使用 Windows Terminal
• 集成 AI 助手：查看 MCP 集成指南
• 无法获取密钥：查看 FAQ
• 临时文件占用空间过大：Windows 系统会在 %TEMP%\filecopy_main 目录创建数据库副本，可能占用大量空间，请参考临时文件清理说明

安装指南

从源码安装

go install github.com/sjzar/chatlog@latest

💡 提示: 部分功能有 cgo 依赖，编译前需确认本地有 C 编译环境。 ⚠️ 注意: go-sqlite3 必须在 CGO_ENABLED=1 时编译才能正常工作。请安装对应平台的 C 编译器（Windows 建议安装 MinGW-w64 并设置 CC；macOS 需安装 Xcode Command Line Tools；Linux 需安装 gcc/clang），然后执行 CGO_ENABLED=1 go build ./cmd/chatlog 或按需配置环境。

下载预编译版本

访问 Releases 页面下载适合您系统的预编译版本。

使用指南

Terminal UI 模式

最简单的使用方式是通过 Terminal UI 界面操作：

chatlog

操作方法：

• 使用 ↑ ↓ 键选择菜单项
• 按 Enter 确认选择
• 按 Esc 返回上级菜单
• 按 Ctrl+C 退出程序

命令行模式

对于熟悉命令行的用户，可以直接使用以下命令：

# 获取微信数据密钥
chatlog key

# 解密数据库文件
chatlog decrypt

# 启动 HTTP 服务
chatlog server

Docker 部署

由于 Docker 部署时，程序运行环境与宿主机隔离，所以不支持获取密钥等操作，需要提前获取密钥数据。

一般用于 NAS 等设备部署，详细指南可参考 Docker 部署指南

0. 获取密钥信息

# 从本机运行 chatlog 获取密钥信息
$ chatlog key
Data Key: [c0163e***ac3dc6]
Image Key: [38636***653361]

1. 拉取镜像

chatlog 提供了两个镜像源：

Docker Hub:

docker pull sjzar/chatlog:latest

GitHub Container Registry (ghcr):

docker pull ghcr.io/sjzar/chatlog:latest

💡 镜像地址:

• Docker Hub: https://hub.docker.com/r/sjzar/chatlog
• GitHub Container Registry: https://ghcr.io/sjzar/chatlog

2. 运行容器

$ docker run -d \
  --name chatlog \
  -p 5030:5030 \
  -v /path/to/your/wechat/data:/app/data \
  sjzar/chatlog:latest

从手机迁移聊天记录

如果电脑端微信聊天记录不全，可以从手机端迁移数据：

1. 打开手机微信，进入 我 - 设置 - 通用 - 聊天记录迁移与备份
2. 选择 迁移 - 迁移到电脑，按照提示操作
3. 完成迁移后，重新运行 chatlog 获取密钥并解密数据

此操作不会影响手机上的聊天记录，只是将数据复制到电脑端

平台特定说明

Windows 版本说明

如遇到界面显示异常（如花屏、乱码等），请使用 Windows Terminal 运行程序

macOS 版本说明

macOS 用户在获取密钥前需要临时关闭 SIP（系统完整性保护）：

1. 关闭 SIP：

   # 进入恢复模式
   # Intel Mac: 重启时按住 Command + R
   # Apple Silicon: 重启时长按电源键
   
   # 在恢复模式中打开终端并执行
   csrutil disable
   
   # 重启系统
   

2. 安装必要工具：

   # 安装 Xcode Command Line Tools
   xcode-select --install
   

3. 获取密钥后：可以重新启用 SIP（csrutil enable），不影响后续使用

Apple Silicon 用户注意：确保微信、chatlog 和终端都不在 Rosetta 模式下运行

临时文件清理

Windows 系统上，程序会在 %TEMP%\filecopy_main 目录创建数据库文件的临时副本（因为 SQLite 在 Windows 上无法直接读取正在使用的数据库文件）。

自动清理机制（已改进）

程序现在具备自动清理机制，无需手动干预：

• ✅ 定期清理：每小时自动清理 24 小时未访问的文件
• ✅ 磁盘空间控制：当占用超过 50GB 时，自动清理到 25GB 以下
• ✅ 版本管理：创建新副本时自动清理旧版本
• ✅ 退出清理：程序退出时清理 1 小时未访问的文件

手动清理（如需要）

如果发现空间占用仍然较大，可以手动清理：

1. 使用清理脚本（推荐）：

   # 预览模式，查看将删除的文件
   .\scripts\cleanup_temp_files.ps1 -WhatIf -DaysOld 7
   
   # 清理7天前的文件
   .\scripts\cleanup_temp_files.ps1 -DaysOld 7
   

2. 手动清理：

   # 清理7天前的文件（先关闭 chatlog 程序）
   Get-Process | Where-Object {$_.ProcessName -like "*chatlog*"} | Stop-Process
   Start-Sleep -Seconds 3
   $cutoffDate = (Get-Date).AddDays(-7)
   Get-ChildItem "C:\Users\$env:USERNAME\AppData\Local\Temp\filecopy_main" -File | 
       Where-Object { $_.LastWriteTime -lt $cutoffDate } | 
       Remove-Item -Force
   

💡 提示：正常情况下，程序会自动管理临时文件，空间占用会保持在 50GB 以下。如果遇到 "Device or resource busy" 错误，说明文件正在被使用，需要先关闭程序。

详细说明请参考：

• 临时文件分析报告
• 彻底解决方案
• 清理指南

HTTP API

启动 HTTP 服务后（默认地址 http://127.0.0.1:5030），可通过以下 API 访问数据：

聊天记录查询

GET /api/v1/chatlog?time=2023-01-01&talker=wxid_xxx

参数说明：

• time: 时间范围，格式为 YYYY-MM-DD 或 YYYY-MM-DD~YYYY-MM-DD
• talker: 聊天对象标识（支持 wxid、群聊 ID、备注名、昵称等）
• limit: 返回记录数量
• offset: 分页偏移量
• format: 输出格式，支持 json、csv 或纯文本

其他 API 接口

• 联系人列表：GET /api/v1/contact
• 群聊列表：GET /api/v1/chatroom
• 会话列表：GET /api/v1/session

多媒体内容

聊天记录中的多媒体内容会通过 HTTP 服务进行提供，可通过以下路径访问：

• 图片内容：GET /image/<id>
• 视频内容：GET /video/<id>
• 文件内容：GET /file/<id>
• 语音内容：GET /voice/<id>
• 多媒体内容：GET /data/<data dir relative path>

当请求图片、视频、文件内容时，将返回 302 跳转到多媒体内容 URL。
当请求语音内容时，将直接返回语音内容，并对原始 SILK 语音做了实时转码 MP3 处理。
多媒体内容 URL 地址为基于数据目录的相对地址，请求多媒体内容将直接返回对应文件，并针对加密图片做了实时解密处理。

Webhook

需开启自动解密功能，当收到特定新消息时，可以通过 HTTP POST 请求将消息推送到指定的 URL。

延迟测试: 本地服务消息回调延迟约 13 秒; 远程同步消息回调延迟约 45 秒。

0. 回调配置

使用 TUI 模式的话，在 $HOME/.chatlog/chatlog.json 配置文件中，新增 webhook 配置。
（Windows 用户的配置文件在 %USERPROFILE%/.chatlog/chatlog.json)

{
  "history": [],
  "last_account": "wxuser_x",
  "webhook": {
    "host": "localhost:5030",                   # 消息中的图片、文件等 URL host
    "items": [
      {
        "url": "http://localhost:8080/webhook", # 必填，webhook 请求的URL，可配置为 n8n 等 webhook 入口 
        "talker": "wxid_123",                   # 必填，需要监控的私聊、群聊名称
        "sender": "",                           # 选填，消息发送者
        "keyword": ""                           # 选填，关键词
      }
    ]
  }
}

使用 server 模式的话，可以通过 CHATLOG_WEBHOOK 环境变量进行设置。

# 方案 1
CHATLOG_WEBHOOK='{"host":"localhost:5030","items":[{"url":"http://localhost:8080/proxy","talker":"wxid_123","sender":"","keyword":""}]}'

# 方案 2（任选一种）
CHATLOG_WEBHOOK_HOST="localhost:5030"
CHATLOG_WEBHOOK_ITEMS='[{"url":"http://localhost:8080/proxy","talker":"wxid_123","sender":"","keyword":""}]'

1. 测试效果

启动 chatlog 并开启自动解密功能，测试回调效果

POST /webhook HTTP/1.1
Host: localhost:8080
Accept-Encoding: gzip
Content-Length: 386
Content-Type: application/json
User-Agent: Go-http-client/1.1

Body:
{
  "keyword": "",
  "lastTime": "2025-08-27 00:00:00",
  "length": 1,
  "messages": [
    {
      "seq": 1756225000000,
      "time": "2025-08-27T00:00:00+08:00",
      "talker": "wxid_123",
      "talkerName": "",
      "isChatRoom": false,
      "sender": "wxid_123",
      "senderName": "Name",
      "isSelf": false,
      "type": 1,
      "subType": 0,
      "content": "测试消息",
      "contents": {
        "host": "localhost:5030"
      }
    }
  ],
  "sender": "",
  "talker": "wxid_123"
}

MCP 集成

Chatlog 支持 MCP (Model Context Protocol) 协议，可与支持 MCP 的 AI 助手无缝集成。
启动 HTTP 服务后，通过 Streamable HTTP Endpoint 访问服务：

GET /mcp

快速集成

Chatlog 可以与多种支持 MCP 的 AI 助手集成，包括：

• ChatWise: 直接支持 Streamable HTTP，在工具设置中添加 http://127.0.0.1:5030/mcp
• Cherry Studio: 直接支持 Streamable HTTP，在 MCP 服务器设置中添加 http://127.0.0.1:5030/mcp

对于不直接支持 Streamable HTTP 的客户端，可以使用 mcp-proxy 工具转发请求：

• Claude Desktop: 通过 mcp-proxy 支持，需要配置 claude_desktop_config.json
• Monica Code: 通过 mcp-proxy 支持，需要配置 VSCode 插件设置

详细集成指南

查看 MCP 集成指南 获取各平台的详细配置步骤和注意事项。

Prompt 示例

为了帮助大家更好地利用 Chatlog 与 AI 助手，我们整理了一些 prompt 示例。希望这些 prompt 可以启发大家更有效地查询和分析聊天记录，获取更精准的信息。

查看 Prompt 指南 获取详细示例。 开启图片 CDN 上传前请阅读 OSS 配置指南。

同时欢迎大家分享使用经验和 prompt！如果您有好的 prompt 示例或使用技巧，请通过 Discussions 进行分享，共同进步。

免责声明

⚠️ 重要提示：使用本项目前，请务必阅读并理解完整的 免责声明。

本项目仅供学习、研究和个人合法使用，禁止用于任何非法目的或未授权访问他人数据。下载、安装或使用本工具即表示您同意遵守免责声明中的所有条款，并自行承担使用过程中的全部风险和法律责任。

摘要（请阅读完整免责声明）

• 仅限处理您自己合法拥有的聊天数据或已获授权的数据
• 严禁用于未经授权获取、查看或分析他人聊天记录
• 开发者不对使用本工具可能导致的任何损失承担责任
• 使用第三方 LLM 服务时，您应遵守这些服务的使用条款和隐私政策

本项目完全免费开源，任何以本项目名义收费的行为均与本项目无关。

License

本项目基于 Apache-2.0 许可证 开源。

隐私政策

本项目不收集任何用户数据。所有数据处理均在用户本地设备上进行。使用第三方服务时，请参阅相应服务的隐私政策。

Thanks

• @0xlane 的 wechat-dump-rs 项目
• @xaoyaoo 的 PyWxDump 项目
• @git-jiadong 的 go-lame 和 go-silk 项目
• Anthropic 的 MCP 协议
• 各个 Go 开源库的贡献者们