核心用法
BillClaw 是一套面向 OpenClaw 用户的完整金融数据管理方案，采用本地优先（Local-First）架构设计。核心功能涵盖三大数据通路：
1. 银行交易同步：集成 Plaid（美加地区）与 GoCardless（欧洲）两大金融数据聚合服务，支持全账户或指定账户同步，可按日期范围筛选。
2. 邮件账单抓取：通过 Gmail OAuth 授权，自动识别并解析账单邮件，支持发件人白名单与自定义过滤规则。
3. 多格式导出：原生支持 Beancount（复式记账）、Ledger（CLI 会计工具）及 CSV 格式，便于与专业会计工作流集成。
使用方式灵活：CLI 提供交互式配置向导（billclaw setup）、同步命令（billclaw sync）及状态监控；OpenClaw 插件则暴露 plaid_sync、gmail_fetch 等 Tools 和 /billclaw-sync 等 Commands，支持自然语言交互。
显著优点
- 数据主权保障：所有交易数据默认存储于本地
~/.billclaw/目录，采用月度分区的 JSON 文件格式，配合可选的 AES-256-GCM 加密，确保敏感财务信息不离本地。 - 企业级凭证安全：通过
keytar调用操作系统原生密钥链（macOS Keychain/Windows Credential/Linux Secret Service）存储 API 密钥，所有访问均记录审计日志。 - 工程化设计：TTL 内存缓存、24小时去重窗口、流式处理大数集、事件驱动架构（
transaction.added、sync.completed等），适合高频同步场景。 - 框架无关核心：
@fire-zu/billclaw-core通过 Logger、ConfigProvider、EventEmitter 等抽象层解耦，可适配 CLI、OpenClaw 及未来平台。
潜在缺点与局限性
- 地域覆盖不均：Plaid 与 GoCardless 均未覆盖亚太地区（中国、日本、东南亚等），这些区域用户无法使用银行同步功能。
- 邮件依赖单一：账单抓取仅支持 Gmail，未覆盖 Outlook、企业邮箱或其他 IMAP 服务，非 Gmail 用户需手动导入。
- 生态成熟度：v0.0.1 初始版本，GitHub 仓库可见度与社区贡献尚处早期，长期维护稳定性待验证。
- 无内置可视化：缺乏原生图表或报表功能，需导出至 Beancount/Fava 等外部工具进行分析。
适合人群
- 追求数据隐私的技术型个人财务管理者
- 已使用 Beancount/Ledger 的复式记账实践者
- 美加欧地区持有银行账户的跨境工作者
- 需要自动化账单归档的自托管爱好者
常规风险
- API 密钥泄露：虽本地存储安全，但用户误操作（如明文备份配置文件）可能导致 Plaid/GoCardless 凭证外泄。
- 同步冲突：多设备同时写入本地 JSON 存储可能引发数据竞争，建议单主机运行或配合文件锁机制。
- 服务依赖：Plaid/GoCardless/Gmail API 策略变更可能影响功能可用性，需关注厂商通知。
- 加密密钥丢失：若启用 AES-256-GCM 加密但未妥善备份密钥，将导致历史数据永久不可读。