Telecrawl 是一个面向 Telegram 历史记录的本地归档与查询工具，以命令行方式使用。它的核心思路是：历史问题优先查本地归档，Telegram 官方应用只用于查看实时/当前状态。
用途 Telecrawl 用于回答与 Telegram 历史相关的问题。它把 Telegram 数据导入本地数据库，从而支持离线、可脚本化的查询，而不依赖 Telegram 应用本身。
数据来源与存储
- 数据库：~/.telecrawl/telecrawl.db
- 导入来源：Telegram Desktop 的 tdata，或 macOS 原生 Telegram Postbox（自动检测）
- 命令行工具：telecrawl
- 归档主机：资料提到当前已填充的归档位于 clawmac（约 200 个聊天）。其他 Mac 上的本地数据库可能为空，因此建议先检查状态，并优先通过 SSH 连接到归档主机，而不是从空数据库作答： ssh -o RequestTTY=no -o RemoteCommand=none steipete@clawmac 'zsh -lc "telecrawl --json status"'
新鲜度检查 使用 telecrawl --json status 查看状态。资料特别提醒：计数为空表示该机器上尚未运行导入，而不是“没有 Telegram 数据”。
查询能力 所有读取命令都接受 --json。示例：
- telecrawl --json chats --limit 20
- telecrawl --json chats --unread
- telecrawl --json messages --chat <ID> --limit 50 --after 2026-01-01
- telecrawl --json search "query" [--chat ID]
- telecrawl --json contacts --limit 50
- telecrawl --json folders
- telecrawl --json topics --chat <ID>
导入与刷新
- telecrawl doctor：验证 Telegram 数据源是否可读
- telecrawl import：从检测到的本地 Telegram 应用进行合并导入
- telecrawl import --fetch-media：同时拉取 Telegram 云端媒体 导入默认按合并方式处理；--restore 会替换归档，属于破坏性操作，应先确认。
备份 支持将加密的 age 分片备份到 git 仓库：
- telecrawl backup status
- telecrawl backup push
适用场景 适合需要检索 Telegram 历史消息、联系人、文件夹与话题的用户，也适合让智能体或脚本通过 JSON 输出访问本地聊天归档。
限制与注意事项
- 本地数据库可能为空，需先运行导入或连接到已填充归档的主机。
- --restore 是破坏性操作。
- 资料未提供收费、价格、平台支持范围、性能指标等更多信息。