# WeChat2Ob 使用手册

**把发给绑定 ClawBot 的微信消息，写成 Obsidian 的 Markdown 日记、Bases 视图与 `.duowei` 表格。**

插件版本 0.1.7 · 配套本机收件服务 0.1.1 · 桌面测试版 · 免费开源（GPL-3.0-only）

源码：[github.com/jepicaju862-lab/wechat2ob](https://github.com/jepicaju862-lab/wechat2ob)

## 安装包下载

按系统下载整包，包内含 Obsidian 插件文件与本机收件服务安装程序。

| 系统 | 下载 | 提取码 |
| --- | --- | --- |
| Windows | [百度网盘 · wechat2ob_win](https://pan.baidu.com/s/1LNtX-1jfKZGGXUyI_5oUtw?pwd=scpu) | `scpu` |
| macOS | [百度网盘 · wechat2ob_mac](https://pan.baidu.com/s/1YxPlVibRNyr37wbTFfC2Ww?pwd=48ra) | `48ra` |

插件源码与 Releases 也可从上面的 GitHub 仓库获取。

---

## 0. 快速开始

1. 下载对应系统的安装包（见上方“安装包下载”），把其中的 `wechat2ob` 文件夹放进库的 `.obsidian/plugins/`，在设置 → 第三方插件中启用（第 2 节）。
2. 解压对应系统的收件服务包并运行 `Install`，用手机微信扫码完成登录（第 3 节）。
3. 回到插件设置点击 **自动连接本机服务**，状态卡应显示「已连接 · 自动同步开启」。
4. 选择输出方式与写入位置，点击 **保存设置**（第 4 节）。
5. 给绑定的 ClawBot 发一条消息，或点设置页底部的 **立即同步** 验证。

已经在用别的微信收件服务时跳过第 2 步，改看 3.2 节的共存说明。

## 1. 安装前要知道的事

WeChat2Ob 由两部分组成：Obsidian 插件，以及一个可独立部署的微信收件服务。插件本身不扫描电脑上的微信数据库，也不读取普通好友的聊天记录——消息必须发送给扫码绑定的 ClawBot。微信账号与接口的可用性取决于上游的实际支持情况。

插件支持 Obsidian 桌面版，声明最低版本 1.11.4，当前不提供手机端插件执行。生成的笔记、附件、Base 和表格文件仍可通过你自己的库同步工具同步到手机上查看。

Bases 的数据来源是 Markdown 笔记与属性，`.base` 保存的是视图配置，不是单独存消息行的数据库。参见 [Obsidian 官方 Bases 说明](https://help.obsidian.md/bases)。

**本插件不做的事：** 不导入完整微信聊天历史，不同步普通好友的所有对话，不提供通用语音识别，不向微信自动回复，不安装服务或修改防火墙。

## 2. 安装插件

1. 完整解压插件包。
2. 把其中的 `wechat2ob` 文件夹复制到目标库的 `.obsidian/plugins/`。
3. 确认该文件夹内有 `main.js`、`manifest.json`、`styles.css`。
4. 在 Obsidian 设置 → 第三方插件中启用 **WeChat2Ob**。
5. 默认自动同步为关闭状态，刚安装时不会主动连接任何服务。

当前尚未上架 Obsidian 官方社区插件市场，需要手动安装。

升级时只替换程序文件，保留本插件的 `data.json` 和 `state/`。

## 3. 连接收件服务

### 3.1 部署本机服务

| 系统 | 包名后缀 | 入口 | 下载 |
| --- | --- | --- | --- |
| Windows 10/11 x64 | `win32-x64.zip` | `Install.cmd` | [wechat2ob_win](https://pan.baidu.com/s/1LNtX-1jfKZGGXUyI_5oUtw?pwd=scpu)，提取码 `scpu` |
| Apple 芯片 Mac，macOS 13.5+ | `darwin-arm64.zip` | `Install.command` | [wechat2ob_mac](https://pan.baidu.com/s/1YxPlVibRNyr37wbTFfC2Ww?pwd=48ra)，提取码 `48ra` |
| Intel Mac，macOS 13.5+ | `darwin-x64.zip` | `Install.command` | 同上 |

完整解压对应服务包，双击入口并用手机微信扫码。包内已含 Node.js、二维码组件和 SILK 解码组件，不需要另装 Node.js、npm、Python、FFmpeg 或 Docker。

首次扫码需要你本人确认，无法自动代替。安装成功后回到插件设置点击「自动连接本机服务」：程序只读取本机的 `connection.json`，把 API Token 保存到本设备的 Obsidian SecretStorage，并开启自动同步（默认间隔 3 秒）。

本机服务默认端口 **7342**，Windows 计划任务名为 `WeChat2Ob Inbox`，Mac LaunchAgent 为 `com.wechat2ob.inbox`。

### 3.2 与已有微信收件服务共存

**同一个 ClawBot 应该只由一个后台服务负责轮询。** 两个服务同时登录同一个 Bot 可能争抢上游消息或导致登录失效，因此不要把旧的 `.env.local`、数据库或 Bot Token 复制到新服务。

如果希望新旧两个插件都收到同一批消息：保留现有服务，在 WeChat2Ob 里手动填写该服务地址和 API Token，保存后点击「立即同步」。两个插件通过各自的客户端 ID 拉取和确认，服务不会因为一个客户端确认就删掉另一个客户端的待收消息。新客户端首次连接时，可能收到服务仍保留的全部历史消息。

不想共享服务时，给新服务使用另一个 ClawBot。

### 3.3 手动部署与远程服务

在服务源码目录执行 `npm ci`，复制 `.env.example` 为 `.env.local`，用 `npm run keygen` 生成密钥，填好配置后执行 `npm run login` 扫码，再 `npm start`。

常用配置项：

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `WEIXIN_MASTER_KEY` | 无 | 加密微信登录凭据的主密钥，只留在服务端，不填进插件 |
| `WECHAT2OB_API_TOKEN` | 无 | 插件连接服务使用的 API Token |
| `INBOX_HOST` | `127.0.0.1` | 监听地址；对外提供必须另加反向代理和 HTTPS |
| `INBOX_PORT` | `7342` | 监听端口 |
| `INBOX_DATA_DIR` | `./runtime-data` | 消息库、附件与日志目录 |
| `WEIXIN_MAX_MEDIA_BYTES` | `104857600` | 单个媒体上限，即 100 MB |

两个密钥不要混用：主密钥只留在服务端，插件里填的是 API Token。手动部署需自行安装 Node.js 24.14+ 并配置后台运行。

跨设备连接请使用 HTTPS 和可靠的认证与网络访问控制，不要把本机 HTTP 端口直接暴露到公网。「自动连接」按钮只支持本机，远程地址需手动填写。不要把含密钥的控制台输出、配置文件或登录二维码发给别人。

### 3.4 二维码获取失败或 TLS 连接重置

出现 `fetch failed / ECONNRESET / secure TLS connection` 表示连接在安全会话建立前或传输途中被中断，不能据此认定密钥损坏。服务 0.1.1 对二维码获取和状态检查的临时网络错误最多尝试 3 次（间隔 1 秒、2 秒），持续失败会给出中文说明并保留密钥、账号与消息。

先稍后重新运行 `Install`。如果之前安装已成功、插件也能同步，就不需要重装或重新扫码。不要删除 `.env.local` 或 `runtime-data/`。

只有在你的网络确实要求代理时，才在**服务安装目录**的 `.env.local` 中加入你已有且信任的代理：

```dotenv
NODE_USE_ENV_PROXY=1
HTTPS_PROXY=http://127.0.0.1:实际代理端口
NO_PROXY=localhost,127.0.0.1,::1
```

Windows 安装目录为 `%LOCALAPPDATA%\WeChat2ObInbox`，Mac 为 `~/Library/Application Support/WeChat2ObInbox`。保留原有密钥行，保存后重新运行 `Install`。不要设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`。

## 4. 输出设置

默认写入方式是 **按日期写入日记**，同一天的消息追加到同一个 `日记/YYYY-MM-DD.md`。日记目录可以改成你现有的日记文件夹，留空则用库根目录。文件名固定为 `YYYY-MM-DD.md`，不会自动读取核心日记插件的目录、命名或模板配置。

也可以选择 **追加到指定文件**，填写库内相对路径，例如 `收件箱/微信.md`。可以指定已有文件，也可以让插件在首次收件时创建；只能用 `.md`，不能指向隐藏配置目录或库外路径。

初次安装的默认值：Markdown 笔记开启、Obsidian Bases 开启、`.duowei` 表格关闭；日记目录 `日记`，时区 `local`，附件与视图目录 `WeChat2Ob`，服务地址 `http://127.0.0.1:7342`，自动同步关闭、间隔 3 秒。库内路径最长 180 字符。

日期按消息的**接收时间**和所选时区计算：今天补收昨天的消息，仍写进昨天的日记。时区默认 `local`，也可填 `Asia/Shanghai`、`UTC` 等 IANA 时区。

「附件与视图目录」默认 `WeChat2Ob`，存放附件、Base 和默认表格，新目录必须为空或已属于本插件。这个限制**不适用于**单独配置的日记目录、指定笔记和目标 `.duowei` 所在目录——它们允许已有内容。

```text
日记/
├─ 2026-08-31.md   ← 当天所有消息追加到这里
└─ 2026-09-01.md
WeChat2Ob/
├─ .wechat2ob-root.json
├─ 附件/2026-08/消息标识-附件标识-voice.wav
├─ 微信笔记.base
└─ 微信收件箱.duowei
```

| 输出 | 行为 |
| --- | --- |
| Markdown 笔记 | 把正文、已有语音转写和附件逐条追加到日记或指定文件末尾，以空行分隔 |
| Obsidian Bases | 按收件笔记路径汇总，一天一篇时一天一行；不会额外生成逐消息笔记 |
| `.duowei` 表格 | 每条消息新增一行；可新建文件，也可映射已有表格的字段 |

三个输出不能同时关闭。改动任何设置后点击 **保存设置**；底部的「立即同步」可立刻拉取待收消息。

已有笔记的 frontmatter、正文和其他小节保持原样。每条新消息接在文件末尾，以空行分隔，**不写**日期标题、时间、发送者、标签、注释或长 ID。去重信息保存在插件 `state/` 中，所以你可以正常编辑和整理笔记。

语音附件由本机服务转成 WAV；**语音识别不是本插件的功能**，只有微信消息本身带转写时才有文字，「语音转写」为空不代表音频缺失。PNG、JPEG、GIF、WebP 图片与 WAV、MP3、M4A、MP4、WebM 音视频以 `![[…]]` 内嵌，其余类型写成 `[[…]]` 链接。附件存放在 `附件与视图目录/附件/YYYY-MM/`，单个附件上限 100 MB，单条消息最多 100 个附件。

`微信笔记.base` 通过文件路径索引收件笔记，自带「微信笔记」和「按目录」两个表格视图。插件只维护自己的路径筛选，保留你的视图、公式和额外筛选。需要按发送者、消息类型逐条筛选时，请使用 `.duowei` 输出。

### 4.1 写入指定的 .duowei 表格

「指定 Markdown 笔记路径」只用于 `.md`，不能填 `.duowei`。

**新建一张指定名称的表格：**

1. 开启 **.duowei 表格输出**。
2. 写入方式选择 **新建 / WeChat2Ob 表格**。
3. 在 **目标 .duowei 文件** 填写库内相对路径，例如 `收件箱/微信消息.duowei`。留空则使用 `WeChat2Ob/微信收件箱.duowei`。
4. 点击 **保存设置**。首次收件时自动创建目录和文件。设置只作用于此后收到的消息，不会重新导入已完成的历史。

**写入已有表格：**

1. 开启表格输出，点击 **选择已有文件** 选择 `.duowei`，或填路径后点击 **读取字段**。
2. 读取过程只做检查，不修改表格。
3. 把 **内容（必选）** 映射到文本或长文本列；展开「其他字段（可选）」按需映射其余项。候选列表显示目标表的实际字段名与中文类型，不兼容或已被占用的字段会置灰并说明原因。
4. 点击 **保存设置**。此后每条新消息新增一行，不改写过去的记录。

| 映射项 | 可接收的列类型 | 写入内容 |
| --- | --- | --- |
| 内容（必选） | 文本、长文本 | 消息正文 |
| 标题 | 文本、长文本 | 消息标题 |
| 消息类型 | 文本、长文本、单选、多选 | 文字 / 图片 / 语音 / 视频 / 文件 / 混合 / 其他 |
| 附件 | 附件 | 库内附件的 `[[路径]]` 列表 |
| 语音转写 | 文本、长文本 | 微信已提供的转写文字 |
| 接收时间 | 日期时间 | 消息接收时间 |
| 发送者 | 文本 | 发送者标识 |
| 会话 | 文本 | 会话标识 |
| 消息唯一键 | 文本 | 本插件的消息键，可不映射 |
| 状态 | 文本、长文本、单选、多选 | 固定写入「待整理」 |
| 笔记 | 笔记链接 | 对应收件笔记的 `[[链接]]` |

不会新增或改型列，不会改写已有行和视图。单选按选项名称匹配并写入对应 ID，多选写入 ID 数组；不会自动创建或改写表内选项，缺少选项或同名选项不唯一时会明确提示并保留消息待重试。公式、关联和自动计算列不能作为接收列。

首次写入普通已有表格前，自动备份到 `.obsidian/plugins/wechat2ob/state/table-backups/<目标散列>/original.duowei`。备份失败时不写入、也不确认该条消息。

## 5. 自动同步与历史数据

自动同步最短 3 秒。电脑和 Obsidian 运行、网络可达时才会写入库；后台服务可在 Obsidian 关闭时继续收件，插件重新打开后拉取服务仍保留的待收消息。每轮最多拉取 50 条，其余留待下一轮；连续失败时自动退避，间隔逐次加倍，最长约 60 秒重试一次。

每条消息先保存私人日志、校验附件、记录待写入信息，再完成所选输出并保存成功记录，最后才确认服务消息。正常重试不会覆盖已完成内容或重复新增表格行。

变更输出设置只影响后续收到的消息，旧输出保留，已确认的历史不会自动搬到新文件。人工删除已完成的笔记段落或表格行，不会被普通同步重新创建。

`state/` 保存历史消息、成功记录和备份，应随库一起备份。

### 5.1 命令、侧边栏图标与状态栏

左侧栏的消息气泡图标 **WeChat2Ob：同步微信消息** 等同于设置页底部的「立即同步」。命令面板提供五条命令：

| 命令 | 作用 |
| --- | --- |
| 立即同步微信消息 | 拉取并写入服务上待收的消息 |
| 自动连接本机 WeChat2Ob 服务 | 读取本机 `connection.json`，保存 Token 并开启自动同步 |
| 打开收件箱 | 打开当前输出对应的文件 |
| 暂停自动同步 | 关闭自动同步 |
| 开启自动同步 | 重新开启自动同步 |

状态栏显示「微信：…」，出错时显示为红色的错误摘要；设置页顶部的状态卡重复同一条状态。

## 6. 安全与数据保存

- API Token 存于本设备的 SecretStorage，不写入插件 `data.json`，也不会自动同步到其他设备。
- 每个本机库生成自己的客户端 ID，保存在本机应用存储。
- 插件 `state/` 保存消息正文、附件路径、输出成功记录和备份，属于私人数据；分发安装包时不能带上 `data.json` 或 `state/`。
- 已有笔记只增加消息段落，不改写原属性；Base 只更新本插件的路径索引；表格追加会保留其他字段、视图与人工记录。
- 同一个目标表格应只由一个写入端管理。多台电脑同时向同一个同步库写表，仍可能受库同步工具的文件冲突影响。

### 6.1 数据存放位置

| 位置 | 内容 |
| --- | --- |
| 日记目录 / 指定笔记 | 收件笔记正文，可随库同步 |
| 附件与视图目录 | 目录标记、`附件/YYYY-MM/`、`微信笔记.base`，以及未指定路径时的默认表格 |
| 目标 `.duowei` | 表格输出 |
| `.obsidian/plugins/wechat2ob/` | `main.js`、`manifest.json`、`styles.css` |
| `.obsidian/plugins/wechat2ob/data.json` | 插件设置；不含 API Token |
| `.obsidian/plugins/wechat2ob/state/` | 私人同步日志、成功回执、表格备份 |
| Obsidian SecretStorage（本设备） | API Token |
| 本机应用存储（本设备） | WeChat2Ob 客户端 ID |
| 服务安装目录 | `.env.local`、`connection.json`、`runtime-data/` |

除插件程序文件外，表中其余内容都是私人数据；提交问题或截图时不要带上它们。

### 6.2 多设备与库同步

- 随库同步的是输出文件。去重和续写依赖 `.obsidian/plugins/wechat2ob/state/`，多数同步工具默认跳过 `.obsidian`，需要自行确认是否纳入同步或备份。
- 去重键由服务地址和消息 ID 计算，不含客户端 ID。若 `state/` 确实同步到另一台设备，同一条消息不会重复追加；若没有同步，另一台设备会按自己的进度重新写一遍服务保留的消息。
- API Token 与客户端 ID 都不随库同步，换设备需要重新连接。
- 同一批笔记和同一张表格应只由一台设备写入。
- 手机端不运行本插件，同步过去的是已生成的笔记、附件、Base 与 `.duowei` 文件。

## 7. 更新和卸载

服务更新：解压新版本服务包并运行 `Install`，保留原密钥、账号和消息；需要重新登录时用 `Repair-login`。运行 `Uninstall` 只停止服务并取消自启，数据和程序文件保留。

卸载插件前请按 6.1 节备份：日记目录或指定笔记、附件与视图目录、目标 `.duowei`，以及 `.obsidian/plugins/wechat2ob/state/`。关闭插件不会删除消息，但 Obsidian 的「卸载插件」可能移除整个插件文件夹，所以不要把同步日志的唯一备份留在该文件夹里。

### 7.1 版本变更速查

| 版本 | 关键变化 | 升级注意 |
| --- | --- | --- |
| 0.1.1 | Markdown 改为按日期写入日记 | 旧的逐条笔记保留，不自动迁移 |
| 0.1.2 | 修复密钥 ID 超过 64 字符 | 升级后重新连接或保存 Token，不必重新扫码 |
| 0.1.3 | 笔记只写纯内容，去重转入私人日志 | 清理旧格式前先备份 |
| 0.1.4 | 独立的表格目标路径与字段映射 | 首次写入已有表格前自动备份原表 |
| 0.1.5 | 精简设置，移除迁移与维护入口 | 旧备份和同步日志保留 |
| 0.1.6 | 允许复用原微信收件表 | 只对本插件自己的消息去重 |
| 0.1.7 | 类型 / 状态支持单选与多选列 | 已有映射需重新点「读取字段」确认类型 |

升级只替换程序文件；`data.json`、`state/`、已生成的笔记与表格都保留。

## 8. 常见问题

| 情况 | 检查 |
| --- | --- |
| 没有收到普通好友消息 | 需要发送给绑定的 ClawBot，本插件不读取所有聊天记录 |
| 自动连接找不到服务 | 是否安装了 WeChat2Ob 本机服务？旧服务需手动填写地址与 Token |
| HTTP 401 | 地址与 Token 是否属于同一个服务？主密钥不是 API Token |
| 提示密钥 ID 无效 | 升级到 0.1.2 或更新版本后重新连接或保存 Token，不要重新扫码或删日志 |
| 获取二维码时 fetch failed / ECONNRESET | 检查网络，必要时按 3.4 节配置可信代理；保留已有数据 |
| Base 没有数据 | 打开 `微信笔记.base`，启用核心 Bases，确认已有收件笔记并检查筛选 |
| 开启表格后没有之前的消息 | 设置只应用于后续消息，不自动迁移旧内容 |
| 表格有新记录但视图看不到 | 检查该视图原有的筛选条件 |
| 类型 / 状态找不到对应列 | 更新至 0.1.7 后点击「读取字段」；灰色候选项旁会说明原因 |
| 提示缺少或重名选项 | 在目标列中提供名称唯一的对应选项，或取消该项映射后保存 |
| 一次只同步了一部分消息 | 每轮最多 50 条，其余在下一轮继续 |
| `.duowei` 显示为 JSON 或打不开 | 需要安装兼容格式的查看插件；WeChat2Ob 只负责输出文件 |
| 附件与视图目录已有其他数据 | 为附件与视图改用空目录；已有日记、笔记和表格填各自的独立设置项 |
| 消息写入了另一个日期 | 检查消息接收时间和日记时区；补收会写回消息所属日期 |
| 附件摘要不匹配 | 文件或下载异常，该消息未确认；检查服务附件或备份，不要直接删除原文件 |
| Mac 提示无法打开 | 服务包尚待真机验收与签名公证；请核验来源并按系统正规流程处理，不要关闭 Gatekeeper |

### 8.1 提示信息对照

| 提示 | 含义与处理 |
| --- | --- |
| 至少选择一种输出 | 三个输出开关不能同时关闭 |
| 远程服务必须使用 HTTPS… | 只有 `127.0.0.1`、`localhost` 允许 http |
| 收件目录必须是库内相对路径… | 路径含特殊字符、以 `/` 开头或超过 180 字符 |
| 收件目录已有其他数据 | 附件与视图目录须为空或已属于本插件 |
| 服务未就绪或尚未扫码登录 | 服务在运行但没有登录账号，先完成扫码 |
| 附件大小或 SHA-256 不匹配，未确认此消息 | 附件不完整，该消息保留待重试 |
| 笔记正在被连续编辑，未追加消息 | 目标笔记同时在被改动，下次同步自动重试 |
| 目标不是支持的独立 .duowei 表格 | 文件格式不受支持，或是只读、实时索引表 |
| 目标表格已被替换，请重新读取字段 | 同一路径换成了另一张表 |
| 表格列缺少 / 存在重名选项 | 单选或多选列缺少对应名称的选项或有重名 |

插件只处理本地文件和你配置的服务请求，不会自动安装服务、修改防火墙、登录微信或发送微信消息。