Billclaw

BillClaw 是一款面向 OpenClaw 用户的本地优先型财务管理技能，旨在为用户提供完全自主的财务数据掌控能力。其核心功能涵盖三大模块：银行交易同步（通过 Plaid 覆盖美加地区、GoCardless 覆盖欧洲）、Gmail 账单自动抓取，以及向 Beancount 或 Ledger 等纯文本会计格式的数据导出。

核心用法：用户通过 CLI 工具 billclaw setup 完成交互式配置，包括银行账户 OAuth 授权、Gmail API 连接及本地存储路径设置。同步操作支持全量、单账户及日期范围筛选，数据以 JSON 格式按月分区存储于 ~/.billclaw/ 目录。导出功能可生成符合复式记账规范的 Beancount 或 Ledger 语法文件，便于与现有会计工作流集成。OpenClaw 集成后提供自然语言交互能力，如「同步上个月的交易记录」。

显著优点：

• 数据主权：银行凭证仅存本地，规避第三方云服务托管风险
• 区域覆盖：Plaid + GoCardless 组合实现欧美主要银行支持
• 生态兼容：原生支持 Beancount/Ledger 开源会计社区标准
• 自动化能力：Gmail 账单解析减少手工录入负担

潜在局限：

• 技术门槛：需自行部署 Connect OAuth 服务（生产环境需 HTTPS 域名及 TLS 证书配置）
• 区域限制：亚洲、南美等地区银行缺乏直接支持
• 维护成本：Plaid/GoCardless API 凭证需定期轮换，OAuth 回调 URI 配置易出错
• 加密可选：本地存储加密非强制，依赖用户安全意识

适合人群：

• 注重隐私的技术型个人用户
• 已使用 Beancount/Ledger 的复式记账实践者
• 需要自动化银行对账的小微企业主
• 欧洲或北美地区的多银行账户持有者

常规风险：

• OAuth 令牌泄露风险（需妥善保管 ~/.billclaw/config.json）
• Gmail 权限过度授权（建议限制仅读取邮件元数据）
• 本地数据丢失（无云备份机制，需用户自行制定备份策略）
• API 速率限制可能导致同步中断

核心功能与用法

BillClaw 是一款面向 OpenClaw 用户的金融数据管理 Skill，采用本地优先架构，核心功能包括：

银行交易同步：支持 Plaid（美国/加拿大）和 GoCardless（欧洲）两大主流银行 API，可将交易数据直接同步至本地存储。安装 CLI 后通过 billclaw setup 进行交互式配置，billclaw sync 执行同步，支持按账户和日期范围筛选。

Gmail 账单自动抓取：通过 OAuth 授权读取 Gmail，自动识别账单邮件，实现无感知的费用追踪。支持配置发件人白名单以提升准确性。

会计格式导出：原生支持 Beancount 和 Ledger 两种纯文本会计格式，满足专业记账需求。导出时可指定日期范围，内置格式映射预览功能。

OpenClaw 深度集成：提供 Agent 工具（plaid_sync、gmail_fetch、conversational_sync）和快捷命令（/billclaw-sync、/billclaw-status），支持自然语言交互如"同步我上个月的银行交易"。

显著优点

• 数据主权：银行凭证和交易数据完全存储于本地（~/.billclaw/），不上传至第三方服务器，隐私风险极低
• 开源生态：基于 MIT 许可，与 Beancount、Ledger 等开源会计工具无缝衔接
• 多区域覆盖：同时支持北美（Plaid）和欧洲（GoCardless）银行体系
• 零代码门槛：纯 Markdown 文档型 Skill，无危险代码执行，即装即用
• 渐进式部署：支持从本地开发（localhost）到生产环境（HTTPS 域名）的平滑迁移

潜在局限与风险

| 维度 | 说明 |

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

| **来源可信度** | T3 级别（个人开发者/社区项目），GitHub 仓库仅 12 stars，单一贡献者，维护可持续性存疑 |

| **功能依赖** | 实际功能依赖外部 npm 包 `@firela/billclaw-cli`，Skill 本身仅为使用文档 |

| **配置复杂度** | 生产部署需自行配置 OAuth 回调、TLS 证书和公网域名，技术门槛较高 |

| **银行覆盖** | 不支持中国大陆及亚太其他地区银行，国内用户无法使用核心功能 |

| **动态 DNS 示例** | 文档包含 ngrok 配置示例，若误用于生产可能暴露本地服务 |

适合人群

• 技术型个人用户：熟悉 CLI 操作、有自托管需求的开发者或量化记账爱好者
• Beancount/Ledger 现有用户：希望自动化银行交易导入的纯文本会计实践者
• 隐私敏感用户：拒绝 SaaS 财务软件、坚持数据本地化的极客群体
• 北美/欧洲居民：持有支持 Plaid/GoCardless 的银行账户

常规风险提示

1. 凭证安全：~/.billclaw/config.json 包含 Plaid Secret 和 Gmail OAuth 凭证，务必设置严格文件权限（chmod 600），禁止提交至 Git
2. npm 包审计：建议在使用前通过 npm audit 检查 @firela/billclaw-cli 的依赖安全状况
3. OAuth 回调防护：生产环境必须使用 HTTPS 固定域名，禁用 ngrok 等动态 DNS 方案传输真实银行数据
4. 数据备份：本地 JSON 存储虽安全，但需自行建立备份机制防止磁盘故障导致数据丢失