Billclaw

核心用法

BillClaw是OpenClaw生态的本地化金融数据管理技能，采用本地优先（local-first）架构，确保用户金融数据完全自主可控。核心工作流包括三步：①通过交互式向导billclaw setup配置Plaid（美/加）或GoCardless（欧洲）银行账户，及Gmail OAuth账单抓取；②执行billclaw sync按需或定时同步交易流水，自动去重（24小时窗口）；③使用billclaw export导出为Beancount双分录格式或Ledger CLI格式。

OpenClaw插件提供自然语言接口，如"同步上月信用卡账单"等指令可直接触发conversational_sync工具，降低命令行门槛。

显著优点

1. 数据主权：明文JSON本地存储于~/.billclaw/，可选AES-256-GCM加密，凭证托管于系统钥匙串（keytar），从根本上杜绝云端数据泄露风险
2. 多源覆盖：Plaid+GoCardless实现欧美主要银行覆盖，Gmail抓取补充账单场景，形成完整财务数据源闭环
3. 会计级输出：原生支持Beancount（量化投资社区主流）和Ledger（极客首选），而非简陋CSV，满足进阶用户复式记账需求
4. 技术开放性：MIT协议、运行时抽象层设计、事件驱动架构，便于二次开发与跨平台移植

潜在缺点与局限性

• 地理覆盖缺口：亚洲（含中国、日本、东南亚）银行无原生API支持，需依赖手动CSV导入或未来扩展
• Gmail依赖：账单抓取深度绑定Google生态，Outlook/企业邮箱用户无法直接使用
• 版本早期风险：0.0.1初始版本，生产环境长期稳定性待验证，Plaid/GoCardless API变更可能影响兼容性
• 无移动端：纯Node.js/CLI工具链，缺乏iOS/Android原生应用，现场消费记录场景受限

适合人群

• 隐私敏感型用户：拒绝Mint/YNAB等云端记账工具的数据托管模式
• 复式记账实践者：已使用或计划迁移至Beancount/Ledger的技术爱好者
• 欧美银行用户：拥有美国、加拿大、欧洲银行账户，需自动化流水同步
• 开发者/自托管爱好者：希望集成金融数据至个人数据仓库或HomeLab场景

常规风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| API凭证泄露 | Plaid/GoCardless Client Secret本地存储 | 启用keychain加密，避免硬编码 |

| 同步冲突 | 多设备同时写入同一JSON存储 | 建议单主设备+定期备份策略 |

| 数据格式演进 | 0.0.x版本存储格式可能不兼容 | 导出为Beancount作为长期存档格式 |

| 邮件隐私 | Gmail读取权限涉及敏感通信 | 创建专用账单接收邮箱隔离权限 |

核心定位与功能架构

BillClaw 是一款面向 OpenClaw 用户的金融数据管理 Skill，采用「本地优先（local-first）」架构设计，核心目标是让用户在享受自动化银行交易同步的同时，完全掌控自己的财务数据主权。该 Skill 本质上是一套纯文档型配置指南，无内置可执行代码，所有功能依赖外部 npm 包实现。

核心功能矩阵

| 功能模块 | 覆盖区域 | 技术实现 |

|---------|---------|---------|

| 银行交易同步 | 美国/加拿大 | Plaid API |

| 银行交易同步 | 欧洲 | GoCardless API |

| 账单邮件抓取 | 全球 | Gmail OAuth |

| 会计格式导出 | 通用 | Beancount / Ledger / CSV |

技术架构特点

存储层：采用 ~/.billclaw/ 本地路径，月度分区 JSON 格式，支持 TTL 内存缓存与 24 小时去重窗口，兼顾查询效率与存储整洁。

安全层：平台密钥链（keytar）存储凭证，可选 AES-256-GCM 加密，审计日志记录所有凭证访问行为，实现「数据不出本地」的隐私承诺。

运行时抽象：核心包（@firela/billclaw-core）框架无关，通过 Logger/ConfigProvider/EventEmitter 抽象接口，支撑 CLI、OpenClaw 插件及未来平台扩展。

显著优点

1. 数据主权闭环：与其他云端记账工具不同，BillClaw 的原始交易数据、解析后的账单、导出文件均存储于用户本地磁盘，符合 GDPR/CCPA 合规要求。

2. 双轨银行覆盖：同时支持北美 Plaid 生态与欧洲 GoCardless 网络，解决跨境用户的区域割裂问题。

3. 会计工具原生兼容：直接输出 Beancount（Python 生态）与 Ledger（C++ 生态）格式，避免传统工具导出 CSV 后的二次转换痛苦。

4. 事件驱动可扩展：内置 transaction.added/sync.completed 等事件钩子，便于用户编写自定义脚本（如交易自动分类、预算预警）。

5. 来源可信度良好：维护方 fire-la 为 GitHub 组织账号（T2 级别），非个人开发者，MIT 开源许可透明。

潜在局限与风险

1. 外部依赖验证负担：实际功能由 @firela/* 系列 npm 包承载，Skill 本身仅为文档。用户需自行执行 npm view 验证包来源，存在「文档可信但实现包被劫持」的供应链风险。

2. OAuth 权限敏感：Gmail 账单抓取需要读取邮件内容的 OAuth 授权，属于高敏感权限。虽然文档建议最小化授权范围，但用户仍需自行管理授权生命周期。

3. 金融 API 凭证管理：Plaid/GoCardless 的 Client ID 与 Secret 配置需要用户具备基础的密钥管理意识，误操作（如硬编码至配置文件）可能导致凭证泄露。

4. 纯文档型 Skill 的功能边界：无代码执行能力意味着所有「智能」功能（如自然语言查询 conversational_sync）均依赖外部包实现，版本兼容性需用户自行把控。

适合人群

• 隐私优先型用户：拒绝将完整银行流水上传至云端记账 SaaS（如 Mint、YNAB）的用户
• 复式记账实践者：已使用或计划迁移至 Beancount/Ledger 的会计极客
• 跨境财务管理者：同时持有北美与欧洲银行账户，需要统一视图的数字游民
• OpenClaw 生态用户：希望在一个会话中完成「银行同步 → 账单解析 → 会计导出」闭环的自动化追求者

常规风险提示

| 风险类别 | 具体表现 | 缓解建议 |

|---------|---------|---------|

| 供应链风险 | `@firela/*` npm 包被恶意篡改 | 安装前执行 `npm view` 验证发布者；锁定版本号 |

| OAuth 过度授权 | Gmail 授权范围超出必要 | 定期审查 Google 账户的第三方应用权限 |

| 本地数据泄露 | `~/.billclaw/` 未加密被读取 | 启用 AES-256-GCM 选项；文件系统权限隔离 |

| API 密钥泄露 | Plaid Secret 误提交至 Git | 使用密钥链存储，禁止硬编码 |

| 交易同步异常 | 重复交易或遗漏 due to 去重逻辑 | 定期人工核对银行账单与本地记录 |

综上，BillClaw 是一款设计理念先进、隐私保护到位的金融数据管理方案，但要求用户具备「信任但验证」的安全意识，主动管理 npm 依赖与 API 凭证的生命周期。