微信到 Obsidian 桥接工具:把微信资料沉淀为 Markdown、摘要和个人知识库素材。
WeChat-to-Obsidian bridge for turning WeChat materials into Markdown, summaries, and PKM assets.
- 先阅读
SKILL.md,确认触发场景、输入要求和执行步骤。 - 按仓库 README 的安装方式复制或安装 Skill。
- 在真实任务中调用前,先用示例或测试脚本做一次小范围验证。
- Read
SKILL.mdfirst to understand triggers, inputs, and workflow steps. - Install or copy the skill according to this README.
- Before using it on real work, run a small example or validation script.
- GitHub 仓库 / Repository: https://github.com/siuserxiaowei/wechat-to-obsidian
- 默认分支 / Default branch:
main - 主要语言 / Primary language:
Python - 可见性 / Visibility:
public - 仓库类型 / Repository type:
source - Topics / 主题:
knowledge-management,markdown,obsidian,wechat,weflow
git clone https://github.com/siuserxiaowei/wechat-to-obsidian.git
cd wechat-to-obsidian
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 -m pytest| 路径 / Path | 中文说明 | English |
|---|---|---|
README.md |
项目入口说明,先读这里。 | Main project entry point and orientation. |
SKILL.md |
Skill 的核心说明、触发条件和执行步骤。 | Core skill instructions, trigger rules, and workflow. |
requirements.txt |
Python 依赖列表。 | Python dependency list. |
assets |
图片、样式、数据等资源。 | Images, styles, data, and other assets. |
docs |
文档或 GitHub Pages 输出目录。 | Documentation or GitHub Pages output. |
scripts |
构建、同步、生成或维护脚本。 | Build, sync, generation, or maintenance scripts. |
tests |
测试用例与验证脚本。 | Tests and validation scripts. |
LICENSE |
许可证文件。 | License file. |
agents |
Agent 配置或平台适配文件。 | Agent configuration or platform adapters. |
configs |
项目文件或目录。 | Project file or directory. |
launchd |
项目文件或目录。 | Project file or directory. |
references |
参考资料、规范或补充说明。 | References, specifications, or supporting notes. |
- 中文:当项目目标、在线入口、运行命令或目录结构变化时,同步更新本说明。
- English: Keep this guide updated when the project purpose, live link, run commands, or structure changes.
- 中文:修改代码、数据或生成页面后,优先运行相关构建、测试或校验命令。
- English: After changing code, data, or generated pages, run the relevant build, test, or validation command.
- 中文:不要提交 API key、token、密码、cookie、私有链接或内部账号资料。
- English: Do not commit API keys, tokens, passwords, cookies, private URLs, or internal account data.
- 中文:公开 GitHub Pages 前,确认资料已脱敏并允许公开。
- English: Before publishing GitHub Pages output, confirm the material is redacted and cleared for public release.
中文介绍:微信 Obsidian Bridge,把微信和 WeFlow 的聊天记录、链接、图片和文件导入 Obsidian Markdown 知识库。
English: A WeChat Obsidian bridge that imports WeChat and WeFlow chat records, links, images, and files into an Obsidian Markdown vault.
SEO 关键词 / SEO Keywords: WeChat, Obsidian, Markdown, PKM, chat export, 知识库
微信 Obsidian 桥:把微信里的聊天记录、文件传输助手、链接、图片、语音、视频和学习资料导入到 Obsidian vault,变成可搜索、可链接、可长期沉淀的 Markdown 知识库。
这个仓库不是一个单纯的备份脚本,而是一个面向个人知识管理的导入桥:
- 通过可插拔 provider 读取本地微信会话,统一导入 Obsidian。
- 默认仍用
jackwener/wx-cli;也可以接入wechat-decryptHTTP 服务或探测wechat-mcp-macos。 - 如果
wx-cli获取不到,可以用本地wechat-cli-pkg.tar.gz解压出来的wechat-cli二进制。 - 仍支持从 WeFlow 导出的 JSON 或 WeFlow 本地 HTTP API 导入 Obsidian。
- 在没有 WeFlow 的情况下,直接处理 macOS 微信 4.x 本地数据库,解密后导出指定聊天。
- 把聊天按日期拆成 Markdown,并把能拿到的媒体文件放到
attachments/。
下面是示意截图,内容使用的是示例数据,不包含真实聊天隐私。
可以做到,但当前形态不是“安装一个 Obsidian 插件后自动同步微信”。
当前是这个链路:
微信
-> wx-cli / wechat-decrypt / wechat-mcp-macos / 本地 wechat-cli 包 / WeFlow
-> wechat2obsidian.py
-> Obsidian vault 里的 Markdown + attachments
-> Obsidian 搜索、标签、反链、图谱、Dataview 等能力
也就是说,它是一个“导入桥”,把微信数据写进 Obsidian vault。写进去之后,Obsidian 会把这些聊天记录当作普通 Markdown 笔记处理。
可以看到大部分本地能拿到的内容:
| 内容 | 当前支持情况 |
|---|---|
| 文本聊天 | 支持,按日期生成 Markdown |
| 文件传输助手 | 支持,推荐优先导入 |
| 群聊 / 私聊 | 支持,需要知道 talker / wxid / @chatroom |
| 链接 / 公众号文章卡片 | 支持渲染为 Markdown 链接,取决于源数据字段 |
| 图片 / 视频 / 语音 / 表情 | 支持复制或引用本地媒体,取决于 WeFlow 或微信本地是否已缓存 |
| 附件文件 | 支持复制到 attachments/,取决于源数据能否给出本地路径 |
| 聊天数据统计 | 当前会生成 manifest;更复杂的年报/统计建议先用 WeFlow,再把结果或数据导入 Obsidian |
| 微信收藏 | 通过 WeFlow 导出或聊天里的收藏/转发内容导入更稳;直接解析 favorite.db 仍属于后续增强 |
不能保证 100% 拿到的内容:
- 只存在云端、没有落到本地缓存的图片/视频/文件。
- 小程序、视频号、朋友圈等复杂云端内容。
- 微信本身没有保存完整原件的历史媒体。
- WeFlow/API 没有返回本地路径的媒体文件。
不是只能使用 WeFlow。现在推荐先用通用 provider 入口选择读取后端,再把结果统一写入 Obsidian。
| 方式 | 推荐度 | 适合场景 | 说明 |
|---|---|---|---|
| wx-cli provider | 默认 | 日常同步、文件传输助手、群聊/私聊 | jackwener/wx-cli 负责读取微信记录,本仓库负责导入 Obsidian |
| wechat-decrypt provider | 优先备用 | 微信 4.x、本地数据库解密、需要 HTTP/MCP 能力 | 启动 wechat-decrypt 的本地服务后,通过 HTTP provider 导入 |
| wechat-mcp-macos provider | 探测中 | macOS MCP 生态 | 当前先做安装/config/ready 探测;稳定 stdio 包装后再作为导入后端 |
| 本地 wechat-cli 包 | 备用 | wx-cli 装不上或获取不到时 |
使用你给的 wechat-cli-pkg.tar.gz 解压后的二进制 |
| WeFlow API / JSON | 兼容 | 已经在用 WeFlow 的场景 | 继续支持,但不再是第一推荐 |
| 直接解微信本地库 | 最后兜底 | 需要底层控制 | 需要 Frida 抓 key、解密 DB,步骤更多 |
推荐顺序:
wx-cli provider -> wechat-decrypt provider -> 本地 wechat-cli 包 -> WeFlow API/JSON -> 直接解微信本地库
不建议把 PyWxDump、已移除的 sjzar/chatlog 原仓库或偏 Windows 的 chatlog_alpha 作为默认依赖;这些项目可能存在兼容、维护或合规风险。WDecipher 当前明确不支持 macOS,也不纳入默认路线。
查看当前可用后端:
python3 scripts/wechat2obsidian.py providers查看某个后端的修复提示:
python3 scripts/wechat2obsidian.py provider-doctor --provider wechat-decrypt \
--base-url http://127.0.0.1:5678用默认 wx-cli provider 导入文件传输助手:
python3 scripts/wechat2obsidian.py import-wechat \
--provider wx-cli \
--chat-id filehelper \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "文件传输助手" \
--page-size 500 \
--max-messages 20000用 wechat-decrypt provider 导入:
# 先在 wechat-decrypt 仓库启动本地服务,默认监听 http://127.0.0.1:5678
python3 main.py
python3 scripts/wechat2obsidian.py import-wechat \
--provider wechat-decrypt \
--base-url http://127.0.0.1:5678 \
--chat-id "1234567890@chatroom" \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--page-size 500 \
--max-messages 50000import-wechat 和旧的 import-wx-cli 使用同一套 Markdown 渲染、附件处理、分页、去重和 manifest 审计字段。默认不会保存 provider 原始响应;只有显式传 --raw-output 时,才会把本地 raw response 保存到导入目录,便于排查。
安装并初始化 jackwener/wx-cli:
npm install -g @jackwener/wx-cli
codesign --force --deep --sign - /Applications/WeChat.app
killall WeChat && open /Applications/WeChat.app
sudo wx init确认能列出会话:
python3 scripts/wechat2obsidian.py wx-sessions --limit 500 --json建议优先从输出里复制唯一的 username,例如 filehelper、wxid_* 或 *@chatroom。群名可能重复,折叠会话里也可能出现占位项;如果用群名称导入且匹配到多个会话,CLI 会停止并列出候选,避免悄悄导错群。
导入文件传输助手:
python3 scripts/wechat2obsidian.py import-wx-cli \
--chat-id filehelper \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "文件传输助手" \
--since 2026-01-01 \
--until 2026-05-01 \
--page-size 500 \
--max-messages 20000 \
--media导入某个群聊:
python3 scripts/wechat2obsidian.py import-wx-cli \
--chat-id "1234567890@chatroom" \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "重要群聊/群名" \
--since 2026-04-01 \
--until 2026-05-01 \
--page-size 500 \
--max-messages 50000也可以用 --chat-name "群名称" 让 CLI 先通过 wx-sessions 解析会话;只有唯一匹配时才会继续导入。导入 manifest 会记录 resolved_session、pages_fetched、raw_message_count、deduped_count、filtered_count、dropped_count、首尾消息时间和 warnings,方便判断这次是否真的抓全。
如果 wx-cli 获取不到,就用你本地的包:
tar -xzf /Users/siuserxiaowei/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/wxid_276exkqyuyd422_20a2/msg/file/2026-04/wechat-cli-pkg.tar.gz -C /tmp/wechat-cli-pkg导入:
python3 scripts/wechat2obsidian.py import-wx-cli \
--binary /tmp/wechat-cli-pkg/wechat-cli-pkg/wechat-cli/node_modules/@canghe_ai/wechat-cli-darwin-arm64/bin/wechat-cli \
--chat-id "群 chatroom id 或 filehelper" \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "wx-cli导入" \
--since 2026-04-01 \
--until 2026-05-01- 打开 WeFlow。
- 进入设置,开启
API 服务。 - 如果设置了 Access Token,复制 token;如果 token 是空的,可以不传。
- 在终端进入本仓库:
cd /Users/siuserxiaowei/Desktop/dont哥\ 对谈/wechat-to-obsidian- 看看 WeFlow API 是否能列出会话:
python3 scripts/wechat2obsidian.py weflow-sessions --keyword 文件如果你想列出更多会话:
python3 scripts/wechat2obsidian.py weflow-sessions --limit 200- 导入文件传输助手到 Obsidian:
python3 scripts/wechat2obsidian.py import-weflow-api \
--talker filehelper \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "文件传输助手" \
--media如果 WeFlow 配了 token:
python3 scripts/wechat2obsidian.py import-weflow-api \
--talker filehelper \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "文件传输助手" \
--token "你的 WeFlow Token" \
--media限制日期范围:
python3 scripts/wechat2obsidian.py import-weflow-api \
--talker filehelper \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "文件传输助手" \
--since 2026-01-01 \
--until 2026-05-01 \
--media导入后 Obsidian 里会出现类似结构:
Obsidian Vault/
└── 微信渠道/
└── 文件传输助手/
├── 2026-01/
│ ├── 2026-01-03.md
│ └── attachments/
├── 2026-02/
│ ├── 2026-02-18.md
│ └── attachments/
└── _weflow_import_manifest.json
如果你已经在 WeFlow 里导出了 JSON 文件:
python3 scripts/wechat2obsidian.py import-weflow-json \
--input ~/Downloads/weflow-export.json \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "某个会话"这条路线适合一次性导入,也适合你先在 WeFlow 里筛选/导出,再进 Obsidian。
这条路线更底层,适合 WeFlow 不可用或你想直接处理 macOS 微信 4.x 本地数据库。
安装依赖:
python3 -m pip install -r requirements.txt检查环境:
python3 scripts/wechat2obsidian.py doctor签名一个可被 Frida attach 的微信副本:
python3 scripts/wechat2obsidian.py sign-wechat \
--dest ~/Desktop/WeChat-Obsidian.app抓取数据库 key:
python3 scripts/wechat2obsidian.py capture-keys \
--wechat-app ~/Desktop/WeChat-Obsidian.app \
--launch \
--wait 300抓 key 时,在微信里打开你要导出的聊天,比如 文件传输助手。
解密 message_0.db:
USER_DIR=$(python3 scripts/wechat2obsidian.py locate-user --print-path)
python3 scripts/wechat2obsidian.py decrypt \
--db "$USER_DIR/db_storage/message/message_0.db" \
--out /tmp/message_0.decrypted.db列出可导出的会话:
python3 scripts/wechat2obsidian.py list-targets \
--db /tmp/message_0.decrypted.db \
--limit 50导出文件传输助手:
python3 scripts/wechat2obsidian.py export-chat \
--db /tmp/message_0.decrypted.db \
--target filehelper \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "文件传输助手" \
--with-senders如果你要管理几百个群、想要增量更新、需要按类型分类和去重,路线 E 的一站式 CLI 不够用。本仓库另外提供了一套模块化脚本(基于 Jane-xiaoer/wechat-to-obsidian 扩展),每个脚本职责单一,组合使用:
| 脚本 | 来源 | 职责 |
|---|---|---|
scripts/extract_key.py |
upstream | Frida hook CCKeyDerivationPBKDF 抓 SQLCipher 密钥 |
scripts/decrypt_db.py |
upstream | AES-256-CBC 按页解密 SQLCipher v4 数据库 |
scripts/export_chat.py |
upstream | 单会话导出 → Markdown 日报 + 附件 |
scripts/list_chats.py |
本仓库 | 跨多个 message DB 列出所有会话,附真实联系人/群名 |
scripts/batch_export.py |
本仓库 | 批量导出,支持 --top N / --skip-existing / 容错 |
scripts/import_real_files.py |
本仓库 | 把 msg/file/ msg/video/ 真实文档按月份 + 类型双视图入库(硬链接,不占额外空间) |
scripts/dedup_attachments.py |
本仓库 | SHA-256 找重复附件,可选择硬链接合并 |
scripts/dedup_msgfile.py |
本仓库 | 清理微信原始 msg/file/ 内的真实重复文件 |
scripts/categorize_attachments.py |
本仓库 | 按文件类型生成 _by_type/ 软链接视图 |
scripts/cleanup_cache.py |
本仓库 | 清理 cache/ 目录的老月份缓存 |
# 1. 抓密钥(一次性,登录后点开你想导出的所有会话)
./run_capture_key.sh
# 2. 增量更新(解密 + 列表 + 批量导出 + 真实文件入库)
./update.shupdate.sh 支持环境变量自定义:
WX_USER_WXID=wxid_xxx_xxxx \
VAULT="$HOME/Documents/MyVault" \
./update.sh详见 USAGE.md。
导入完成后,打开你的 Obsidian vault:
- 左侧文件树会看到
微信渠道/文件传输助手/2026-xx/2026-xx-xx.md。 - 每天一个 Markdown 文件。
- 每条消息是一个时间戳小标题。
- 图片、视频、语音、文件会尽量放在同月份的
attachments/。 - 链接类消息会尽量渲染成 Markdown 链接。
- 你可以用 Obsidian 全文搜索、标签、反链、图谱、Dataview 等插件继续整理。
已经准备了一份可以直接放进 Obsidian 的配置手册:
docs/Obsidian-微信资料库配置.md
里面包含推荐目录、WeFlow 设置、导入命令、Dataview 查询、搜索语法、日常同步流程和排错清单。
这点很重要:
- 不能直接在 Obsidian 社区插件里搜索安装。
- 不是安装 Obsidian 后自动同步微信。
- 当前需要你运行一次 CLI 命令,把数据导入 vault。
- 后续可以在这个仓库上继续做一个真正的 Obsidian 插件,把按钮、同步任务、配置界面都放进 Obsidian。
# 检查环境
python3 scripts/wechat2obsidian.py doctor
# 列出可插拔微信读取后端
python3 scripts/wechat2obsidian.py providers
# 检查某个 provider
python3 scripts/wechat2obsidian.py provider-doctor --provider wx-cli
# 列 wx-cli 会话
python3 scripts/wechat2obsidian.py wx-sessions --limit 100
# 通用 provider 导入入口
python3 scripts/wechat2obsidian.py import-wechat \
--provider wx-cli \
--chat-id filehelper \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "文件传输助手" \
--page-size 500 \
--max-messages 20000
# 从 wx-cli 导入文件传输助手
python3 scripts/wechat2obsidian.py import-wx-cli \
--chat-id filehelper \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "文件传输助手" \
--page-size 500 \
--max-messages 20000 \
--media
# 从 WeFlow JSON 导入
python3 scripts/wechat2obsidian.py import-weflow-json \
--input ~/Downloads/weflow-export.json \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道"每天只跑一条命令:
python3 scripts/group_daily_pipeline.py \
--chat "付费群名称" \
--date yesterday \
--vault ~/Documents/Obsidian\ Vault \
--folder "微信渠道" \
--subfolder "付费群/付费群名称"它会自动完成:
读取群聊 -> 写入 Obsidian 原始记录 -> 生成干货分析 -> 生成日报 HTML/PNG
批量跑多个群,复制配置样例:
cp configs/group_daily.example.json configs/group_daily.json编辑 configs/group_daily.json 里的 vault 和 groups,然后运行:
python3 scripts/group_daily_pipeline.py \
--config configs/group_daily.json \
--date yesterday如果你要把 HTML/PNG 发布到 GitHub Pages,在配置里填写:
"publish": {
"repo": "/path/to/github-pages-repo",
"base_url": "https://你的用户名.github.io/你的仓库",
"push": true,
"privacy": "demo"
}发布后的路径固定是:
https://你的用户名.github.io/你的仓库/reports/<公开slug>/<日期>/
privacy: "demo" 是默认公开模式:GitHub Pages 只展示匿名演示页,不会公开真实群名、成员名、头像、聊天原文、链接、词云和具体话题。每个群可以配置对外显示名:
{
"chat": "真实群名",
"title": "真实群名",
"slug": "private-slug",
"public_title": "一群",
"public_slug": "group-1"
}只有你明确把 privacy 改成 "full",才会把完整日报 HTML 复制到 GitHub Pages。公开演示不建议这样做。
如果要在跑完后同步提醒飞书和 Telegram,复制本地环境变量样例:
cp configs/group_daily.env.example configs/group_daily.env编辑 configs/group_daily.env,填入:
TELEGRAM_BOT_TOKEN=你的 Telegram Bot Token
TELEGRAM_CHAT_ID=你的 Telegram Chat ID
FEISHU_WEBHOOK_URL=你的飞书自定义机器人 Webhook
FEISHU_WEBHOOK_SECRET=飞书机器人签名密钥,可选然后在 configs/group_daily.json 里保留 env_file 并打开通知:
"env_file": "configs/group_daily.env",
"notify": {
"telegram": {
"enabled": true,
"bot_token_env": "TELEGRAM_BOT_TOKEN",
"chat_id_env": "TELEGRAM_CHAT_ID"
},
"feishu": {
"enabled": true,
"webhook_url_env": "FEISHU_WEBHOOK_URL",
"secret_env": "FEISHU_WEBHOOK_SECRET"
}
}通知内容只包含日期、群名、消息数、活跃人数和日报链接,不会把原始聊天内容发到 IM。
本机每天早上自动跑,建议用 Codex 自动任务或系统定时任务执行:
cd /Users/siuserxiaowei/Desktop/dont哥\ 对谈/wechat-to-obsidian
python3 scripts/group_daily_pipeline.py --config configs/group_daily.json --date yesterday- 只处理你自己的微信数据。
- 不要把 key log、解密后的数据库、聊天附件上传到公开仓库。
.gitignore已经默认排除数据库、key log、导出目录等敏感文件。- 优先使用
jackwener/wx-cli,避免自己维护 Frida 抓 key 和数据库解密链路。
这个项目参考和吸收了这些公开项目的思路:
Jane-xiaoer/wechat-to-obsidianjackwener/wx-clizhuyansen/wx-favorites-reporthicccc77/WeFlowILoveBingLu/CipherTalk
详细说明见 NOTICE 和 references/upstream-projects.md。
想交流 AI 工具、内容自动化、SEO、私域增长或项目合作,可以扫码加我微信。
For collaboration on AI tools, content automation, SEO, private-domain growth, or product experiments, scan the WeChat QR code below.
关键词 / Keywords: WeChat, Obsidian, Markdown, PKM, AI tools, AI automation, GitHub Pages, SEO





