billclaw

BillClaw 是一款专为 OpenClaw 生态设计的金融数据管理 Skill，采用本地优先（Local-First）架构，旨在帮助用户实现银行交易记录与账单数据的自主管理。

核心用法：用户需安装 @firela/billclaw-openclaw npm 包作为插件，通过 plaid_sync 工具同步 Plaid/GoCardless 银行交易，使用 gmail_fetch 自动抓取邮件账单，并利用 /billclaw-export 命令将数据导出为 Beancount 或 Ledger 会计格式。所有操作需通过显式命令或自然语言指令触发，数据默认存储于本地 ~/.billclaw/ 目录，采用 JSON 格式按月分区保存。

显著优点：首先是数据主权保障，金融数据完全本地存储，配合系统密钥链加密敏感令牌，杜绝云端泄露风险。其次是多源整合能力，覆盖北美（Plaid）、欧洲（GoCardless）及全球 Gmail 账单源。第三是会计生态兼容性，原生支持 Beancount 和 Ledger 双格式，满足复式记账用户需求。此外，开源 MIT 协议确保代码透明可审计，disable-model-invocation: true 设计防止模型擅自操作财务数据。

潜在缺点：Skill 本身为纯文档型配置，实际功能完全依赖外部 npm 包（@firela/* 系列），存在供应链安全风险。配置门槛较高，需自行申请 Plaid Dashboard 和 Google Cloud Console 开发者凭据。地域支持不均衡，亚洲银行机构覆盖有限。作为 T3 来源的个人项目，长期维护稳定性与持续性存疑。

适合群体：注重隐私的技术型用户、Beancount/Ledger 记账爱好者、需要自动化银行对账的财务工作者，以及具备 Node.js 环境配置能力、希望本地化管控金融数据的个人用户。

使用风险：需信任 @firela npm 组织的代码安全性，建议在使用前审查依赖包源码。API 密钥（PLAID_SECRET、GMAIL_CLIENT_SECRET）若泄露可能导致金融账户风险，应避免硬编码于配置文件。首次使用建议在沙箱环境验证 Plaid 集成，并关注 npm 包的安全更新公告。

核心用法

BillClaw 是面向 OpenClaw 用户的金融数据管理工具链配置指南，非可执行 Skill，仅提供标准化安装与使用文档。用户通过安装 @firela/billclaw-openclaw npm 包获得四项核心能力：

1. 银行交易同步：通过 Plaid（北美）或 GoCardless（欧洲）API 拉取账户流水
2. 邮件账单抓取：利用 Gmail OAuth 自动识别并提取账单 PDF/图片附件
3. 对话式交互：自然语言指令触发同步（如"同步上月信用卡交易"）
4. 会计格式导出：一键生成 Beancount 或 Ledger 格式的复式记账文件

配置采用分层设计：环境变量 > ~/.billclaw/config.json > OpenClaw 内置配置。数据严格本地化存储于 ~/.billclaw/，按月分区 JSON 格式，敏感 Token 由系统钥匙串加密托管。

显著优点

• 数据主权完整：本地优先架构（local-first），财务数据永不离开用户设备，符合 GDPR 数据最小化原则
• 凭证自主可控：Plaid/Gmail API 密钥由用户自行申请并保管，Skill 零托管、零硬编码
• 开源可审计：MIT 许可证，GitHub 完整开源，npm 包独立发布可逐行审查
• 区域覆盖全面：Plaid 覆盖美加、GoCardless 覆盖欧洲、Gmail 全球可用
• 无遥测设计：零追踪、零上报，隐私合规六项检测全通过

潜在局限

• 非开箱即用：需自行注册 Plaid/Gmail 开发者账号并配置 OAuth，技术门槛较高
• 区域服务依赖：银行同步受限于 Plaid/GoCardless 的机构覆盖范围，部分小众银行可能不支持
• 纯文档 Skill：无可执行代码，实际功能依赖外部 npm 包，版本兼容性需自行维护
• 无实时同步：基于拉取模式，非 Webhook 实时推送，存在数据延迟

适合人群

• 个人财务极客（Personal Finance Geek）与复式记账实践者
• 对数据隐私敏感、拒绝 SaaS 化财务管理工具的用户
• Beancount/Ledger 等文本记账格式的现有用户
• 具备基础 Node.js 环境配置能力的开发者或技术爱好者

常规风险

| 风险类别 | 说明 | 缓解措施 |

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

| 凭证泄露 | 用户自管的 API 密钥若保管不当可能被窃取 | 使用系统钥匙串存储，避免明文写入配置文件 |

| 供应链攻击 | 依赖的 npm 包被恶意篡改 | 锁定版本号、启用 npm audit、校验包哈希 |

| 本地数据丢失 | `~/.billclaw/` 未备份导致历史交易丢失 | 定期同步至加密备份介质 |

| OAuth 钓鱼 | 伪造的授权页面骗取 Gmail/Plaid 权限 | 仅通过官方域名（plaid.com、google.com）完成授权 |

整体而言，BillClaw 是财务自主理念的技术实现，安全架构设计优秀，适合愿意投入配置成本以换取数据主权的进阶用户。