birdclaw：把 Twitter 历史装进本地 SQLite，让 Agent 慢慢抓

它解决什么问题：Twitter 历史的本地化与可抓取性

Twitter/X 的搜索接口对普通用户越来越不友好，历史数据随时可能被平台调整或删除。birdclaw 的思路很直接：把你的 Twitter 归档导入本地 SQLite，然后通过命令行、Web 界面或 MCP 服务器来访问这些数据。它不依赖任何云端后端，所有数据都留在你自己的机器上。这个项目面向的是那些想要长期保存自己的推文、私信、收藏和关注关系的人，尤其是需要让 AI Agent 能够稳定读取这些数据的人。README 里明确说，它“makes no network requests”，这意味着本地读取永远不会触发网络流量。这一点对隐私敏感的用户来说是个关键卖点。

工作机制：从归档到 SQLite，再到 FTS5 搜索

birdclaw 的核心是 SQLite 数据库。它把 Twitter 归档中的 tweets、DMs、likes、bookmarks、profiles、media 和 follow edges 全部导入到同一个数据库里。导入过程是幂等的，也就是说重复执行不会产生重复数据，而且默认会合并目标数据库中已有的行。搜索功能依赖 SQLite 的 FTS5 全文索引，这让本地搜索变得快速且无需网络。数据存储位置在 ~/.birdclaw 目录下，你可以通过设置 BIRDCLAW_HOME 环境变量来改变这个根目录。这种设计让整个数据流变得清晰：归档导入、实时同步（可选）、本地查询，所有路径都汇聚到同一个 SQLite 文件。

安装与快速上手：Homebrew 和 npm 两条路

安装方式有两种。在 macOS 和 Linux 上，Homebrew 是最短的路径：brew install steipete/tap/birdclaw。如果你更习惯 npm，可以执行 npm install -g birdclaw。需要注意，npm 和 Homebrew 安装都要求 Node.js 版本在 >=26.5.1 <27 之间，这是一个比较严格的版本约束。快速开始也很简单：运行 birdclaw init --demo 创建一个包含示例数据的数据库，然后 birdclaw search tweets "local-first" --limit 3 --json 进行本地搜索，最后 birdclaw serve 启动 Web 服务器，打开 http://localhost:3000 就能浏览。这个 demo 不需要任何凭证或网络请求，适合先体验一下。

实时同步：可选但需要额外工具

虽然本地搜索和归档导入不需要登录 X，但如果你想要获取最新的推文或书签，就需要使用实时同步功能。birdclaw sync timeline --limit 100 --refresh --json 这样的命令会调用外部工具 xurl，或者依赖一个已有的私有 bird 安装。这里有一个明显的依赖点：你必须先配置好 xurl 的登录凭证，否则同步无法工作。README 提到“Import an archive before the first live sync on a new database”，这意味着第一次同步前必须导入归档，否则数据库可能缺少必要的身份信息。而且同步只会按需运行，不会自动后台拉取，这既是好事（控制网络请求），也是限制（需要手动触发或设置定时任务）。

MCP 服务器：为 Agent 提供只读接口

birdclaw 附带一个可选的 MCP（Model Context Protocol）服务器，它提供只读的缓存推文搜索和线程工具。这个服务器默认是关闭的，需要配置一个专用 token 和公开 URL 才会启用。这意味着如果你想让 AI Agent 通过 MCP 访问你的 Twitter 历史，你必须自己管理这个 token 的安全性。MCP 服务器的设计是只读的，这避免了 Agent 意外修改数据。但这也意味着你不能通过 MCP 进行任何写操作，比如发推或删除，这类操作只能通过 CLI 或 Web 界面完成。对于需要让 Agent 读取大量历史数据的场景，这个 MCP 接口比直接让 Agent 调用 CLI 更干净，因为它有明确的权限边界。

限制与失败模式：版本约束和网络依赖的边界

birdclaw 的严格 Node.js 版本约束（>=26.5.1 <27）可能是一个麻烦。如果你正在运行一个旧的 Node LTS 版本，或者使用系统自带的 Node，可能无法满足要求。开发环境使用了一个校验和固定的 Bun 1.4.0-canary.1 构建，但那是针对源码开发，不是安装包。另一个限制是实时同步依赖外部工具 xurl，这意味着如果你不想配置 xurl，就无法获取最新数据。另外，虽然本地读取不产生网络请求，但同步操作本身会发起网络请求，所以如果你在离线环境下使用，只能依赖归档导入。最后，数据库和媒体文件都存储在 ~/.birdclaw 下，如果归档很大，磁盘占用会快速增长，这一点在 README 中没有给出具体数字，但可以预期。

替代方案：与原生 X API 或云服务的对比

如果你不想用 birdclaw，最直接的替代方案是直接使用 X 的官方 API 来拉取数据。但官方 API 有速率限制，而且历史数据的获取往往需要付费订阅。另一个替代是使用像 TweetDeck 或第三方分析工具，但它们通常不提供本地存储。birdclaw 的独特之处在于它把数据完全本地化，并且通过 SQLite 和 FTS5 提供了可编程的访问接口。相比之下，官方 API 更适合需要实时数据流的应用，而 birdclaw 更适合需要长期保存和离线分析的场景。如果你已经有完整的 Twitter 归档，那么 birdclaw 的导入流程比手动处理 JSON 文件要省事得多。

维护与升级成本：版本策略和许可证

birdclaw 采用 MIT 许可证，这意味着你可以自由使用、修改和分发，只要保留版权声明。项目由 Peter Steinberger 创建，没有关联 X Corp。从最近的发布记录看，v0.12.1 在 2026 年 8 月发布，说明项目还在活跃维护。升级成本方面，由于 npm 和 Homebrew 安装都绑定了严格的 Node 版本范围，升级 birdclaw 时你需要确保 Node 版本仍然匹配。开发环境的 Bun 版本是校验和固定的，这保证了可重复构建，但也意味着如果你想用更新的 Bun，需要手动更新配置文件。备份功能使用 JSONL 分片，可以兼容 Git 版本控制，这降低了数据迁移的复杂度。

编辑结论

birdclaw 适合那些拥有 Twitter/X 归档、希望摆脱云端依赖、并且需要让本地 Agent 稳定读取历史数据的人。它不适合没有归档、依赖实时同步、或者需要频繁写入的团队。在采用前，先确认你的 Node.js 版本在 >=26.5.1 <27 范围内，并检查 ~/.birdclaw 目录的磁盘空间，因为媒体文件会随导入增长。还要验证 MCP 服务器的 token 配置是否满足你的安全要求，因为默认情况下它不会自动开启。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes