BillClaw — OpenClaw 的财务数据管理工具

面向 OpenClaw 的完整财务数据管理方案，采用本地优先（local-first）架构。支持同步银行交易、从邮箱自动抓取账单，并导出为多种会计格式。

安全性与可信度

BillClaw 是一款安全、开源的软件，自设计之初即贯彻“安全优先”原则。

验证机制

• 透明的软件包：所有 npm 包均为开源，且通过 provenance（来源证明）发布
• 可审计的代码：全部源码托管于 GitHub，公开可查
• npm provenance：通过密码学手段将发布的软件包与其源代码进行绑定验证
• 本地优先：您的财务数据永不离开您的设备
• 用户自主控制凭证：所有 API 凭证均由您通过自有账户提供
• 系统密钥链集成：访问令牌加密后存储于您所在平台的安全密钥链中
• 显式调用机制：需用户明确触发（disable-model-invocation: true）

详见 SECURITY.md，了解详细的安全架构与验证步骤。

常见安全疑虑说明

所需凭证

重要提示：安装时无需提供任何凭证。仅在启用特定功能前按需配置：

凭证获取地址：

• Plaid：https://dashboard.plaid.com/
• Gmail：https://console.cloud.google.com/apis/credentials

配置方式：

1. 环境变量（推荐）
2. 配置文件（~/.firela/billclaw/config.json）
3. OpenClaw 配置中的 skills.entries.billclaw.env 字段

快速上手（OpenClaw）

1. 安装插件

npm install @firela/billclaw-openclaw

该插件将向 OpenClaw 注册以下工具与命令：

• 工具：plaid_sync、gmail_fetch、conversational_sync、conversational_status
• 命令：/billclaw-setup、/billclaw-sync、/billclaw-status、/billclaw-config

2. 配置凭证

当您准备启用某项功能时，请配置对应凭证：

# 用于 Plaid 银行同步
export PLAID_CLIENT_ID="your_client_id"
export PLAID_SECRET="your_secret"

# 用于 Gmail 账单抓取
export GMAIL_CLIENT_ID="your_client_id"
export GMAIL_CLIENT_SECRET="your_secret"

3. 设置账户

/billclaw-setup

交互式向导将引导您完成以下操作：

• 连接银行账户（Plaid / GoCardless）
• 配置 Gmail 以实现账单自动抓取
• 设定本地存储路径

4. 同步数据

You: Sync my bank transactions for last month

OpenClaw: [Uses plaid_sync tool from BillClaw plugin]
Synced 127 transactions from checking account

或直接使用命令：

/billclaw-sync --from 2024-01-01 --to 2024-12-31

5. 导出为会计格式

/billclaw-export --format beancount --output 2024.beancount

OpenClaw 集成说明

本技能文档介绍如何在 OpenClaw 中使用 BillClaw。实际集成能力由 @firela/billclaw-openclaw npm 包提供。

可用工具（通过插件提供）

• plaid_sync —— 从 Plaid 同步银行交易
• gmail_fetch —— 从 Gmail 抓取账单
• conversational_sync —— 基于自然语言的同步接口
• conversational_status —— 查询同步状态

可用命令（通过插件提供）

• /billclaw-setup —— 配置账户
• /billclaw-sync —— 同步交易记录
• /billclaw-status —— 查看同步状态
• /billclaw-config —— 管理配置项

附加组件（可选）

独立 CLI 工具

面向偏好命令行操作的用户，我们提供了独立的 CLI 工具，作为单独的 npm 包发布。安装说明请参阅：https://github.com/fire-la/billclaw

Connect OAuth Server

如需自托管 OAuth 授权流程，Connect 服务端亦作为独立 npm 包提供。配置详情请参阅：https://github.com/fire-la/billclaw

数据源

存储

• 存储位置：~/.firela/billclaw/（位于您的主目录下）
• 存储格式：按月分区的 JSON 文件
• 安全性：仅限本地存储，不上传至任何远程服务

配置

配置文件保存于 ~/.firela/billclaw/config.json：

{
  "plaid": {
    "clientId": "your_client_id",
    "secret": "your_secret",
    "environment": "sandbox"
  },
  "gmail": {
    "clientId": "your_gmail_client_id",
    "clientSecret": "your_gmail_client_secret"
  }
}

导出格式

Beancount

2024/01/15 * "Starbucks"
  Expenses:Coffee
  Liabilities:CreditCard:Visa
    $5.50

Ledger

2024/01/15 Starbucks
  Expenses:Coffee  $5.50
  Liabilities:Credit Card:Visa

获取帮助

• 文档：https://github.com/fire-la/billclaw
• 问题反馈（Issues）：https://github.com/fire-la/billclaw/issues
• 安全漏洞报告：请通过 security@fire-la.dev 私密提交
• npm 包列表：https://www.npmjs.com/org/firela