Billclaw

核心功能

BillClaw 是一款面向 OpenClaw 用户的开源财务管理技能，采用本地优先架构实现数据主权。核心能力包括：

• 银行交易同步：通过 Plaid（美/加）或 GoCardless（欧洲）直连银行账户，自动拉取交易记录
• 邮件账单抓取：智能解析 Gmail 中的电子账单，自动归类消费
• 会计格式导出：原生支持 Beancount 和 Ledger 两种专业复式记账格式

安全与隐私设计

该工具将安全性置于架构核心：

• 纯本地存储：所有交易数据存放于 ~/.billclaw/ 目录，不上传任何第三方服务器
• 系统钥匙串加密：Plaid 访问令牌、Gmail 刷新令牌均存储于平台原生密钥管理器（macOS Keychain/Windows Credential Manager/Linux Secret Service）
• 最小权限原则：仅访问本地数据目录，无后台自主调用机制，需用户显式触发
• 完全开源可审计：MIT 协议，代码托管于 GitHub

使用方式

提供两层接入方式：
1. OpenClaw 插件（推荐）：@firela/billclaw-openclaw 注册 plaid_sync、gmail_fetch 等工具及 /billclaw-sync 等斜杠命令
2. 独立 CLI：@firela/billclaw-cli 提供完整命令行交互

显著优点

• 数据主权：解决传统记账 SaaS 的数据托管痛点，金融隐私完全自控
• 专业会计集成：原生对接 Beancount/Ledger，满足进阶用户对复式记账、Git 版本控制的需求
• 模块化设计：CLI、Connect OAuth 服务、OpenClaw 插件可独立选用

局限与风险

• 自托管门槛：需自行申请 Plaid/Gmail API 密钥，配置 OAuth 回调，对非技术用户存在学习曲线
• 地域限制：Plaid 覆盖美加、GoCardless 覆盖欧洲，其他地区银行支持有限
• 无云端备份：本地磁盘故障可能导致数据丢失，需用户自行建立备份机制
• 维护责任：开源项目无商业 SLA，安全更新依赖社区或自我维护

适合人群

• 技术背景较强的个人财务管理者
• 重视数据隐私、拒绝云端 SaaS 的"自托管"倡导者
• Beancount/Ledger 现有用户，希望自动化交易录入流程
• 北美/欧洲地区的开发者或高级用户

常规风险提示

1. API 密钥管理：PLAID_SECRET 等敏感配置若泄露，可能导致银行账户访问权限被盗
2. OAuth 回调安全：自托管 Connect 服务时，需正确配置 TLS 和回调域名，防止授权码劫持
3. 数据备份缺失：本地 JSON 存储无自动云备份，建议配合 Git 或 rsync 建立冗余
4. 合规边界：个人使用 Plaid/GoCardless 需遵守其服务条款，高频或商业用途可能触发限制

核心功能

BillClaw 是一款面向 OpenClaw 用户的财务数据管理 Skill，采用本地优先（Local-First）架构，让用户完全掌控自己的银行交易数据。

主要能力：

• 银行同步：通过 Plaid（美国/加拿大）或 GoCardless（欧洲）同步银行账户交易
• 账单抓取：从 Gmail 自动提取电子账单，智能识别消费记录
• 会计导出：支持导出为 Beancount 或 Ledger 格式的记账文件
• 本地存储：所有数据仅存储在 ~/.billclaw/ 目录，不上传任何云端

技术架构：
该 Skill 为指令型设计，本身不直接执行网络或文件操作。实际功能由用户自主安装的 npm 包（@firela/billclaw-cli、@firela/billclaw-openclaw）在独立进程中完成。敏感凭证（Plaid access token、Gmail refresh token）使用系统密钥链（macOS Keychain / Windows Credential Manager / Linux Secret Service）加密存储，交易数据以 JSON 格式本地保存。

显著优点

1. 数据主权：财务数据完全本地存储，不存在第三方服务商数据泄露风险
2. 隐私保护：无云端依赖，无遥测上报，符合 GDPR/CCPA 合规要求
3. 开源可审计：MIT 许可证，完整源码托管于 GitHub，安全漏洞设有专门披露渠道
4. 权限边界清晰：Skill 仅提供指令指导，实际操作由用户可控的外部包执行
5. 标准格式支持：原生支持 Beancount/Ledger 两款主流复式记账格式，便于与现有会计工作流集成

潜在局限

• 配置门槛：需用户自行从 Plaid Dashboard 和 Google Cloud Console 申请 API 凭证，对非技术用户有一定门槛
• 功能依赖外部包：核心功能依赖 npm 生态，需用户自行承担依赖包的安全更新责任
• 区域限制：Plaid 支持美加银行，GoCardless 覆盖欧洲，其他区域银行支持有限
• 无自动化托管：缺乏云端托管选项，多设备同步需用户自行解决

适合人群

• 隐私敏感型用户：不愿将银行数据托管给 Mint、YNAB 等第三方服务
• 复式记账用户：使用 Beancount/Ledger 进行精细化个人/家庭财务管理
• 技术用户：具备基础 API 配置能力，能自主管理凭证和 npm 依赖
• 数据合规需求者：需要满足数据本地化存储要求的企业或个人

常规风险与建议

| 风险点 | 说明 | 缓解建议 |

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

| API 凭证泄露 | 用户配置的 Plaid/Gmail 密钥若管理不善可能被窃取 | 使用环境变量存储，定期轮换密钥（建议 90 天） |

| 依赖包供应链攻击 | `@firela/billclaw-cli` 等包存在被恶意篡改可能 | 安装后运行 `npm audit`，锁定版本号 |

| 本地数据丢失 | 无云端备份，硬件故障可能导致数据不可恢复 | 定期备份 `~/.billclaw/` 目录 |

| 最小权限配置 | 过度授权 API 可能暴露不必要的数据范围 | Plaid 仅启用 transactions 只读，Gmail 限制邮件读取范围 |

安全扫描结果显示：无危险代码模式、无敏感信息硬编码、无恶意依赖，整体安全评级为 S（优秀）。来源可信度 T2（可信组织/GitHub 项目）。