BillClaw - 专为OpenClaw设计的金融数据管理工具

采用本地优先架构，为OpenClaw提供完整的金融数据管理方案。同步银行交易记录、从邮箱抓取账单，并导出为会计格式。

安全与信任

BillClaw是遵循安全优先原则设计的开源安全软件。

可验证性

• 透明化软件包：所有npm软件包均为开源且附带来源证明
• 可审计代码：完整源代码发布于GitHub平台
• npm来源验证：通过密码学证明将软件包与源代码关联
• 本地优先架构：您的金融数据永不离开本地设备
• 用户自主凭证管理：所有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. 配置凭据

当您准备使用某一功能时，请配置所需的凭据：

# For Plaid bank sync
export PLAID_CLIENT_ID="your_client_id"
export PLAID_SECRET="your_secret"

# For Gmail bill fetching
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 集成

此技能提供了将BillClaw与OpenClaw结合使用的说明。实际集成功能由@firela/billclaw-openclawnpm包提供。

可用工具（通过插件）

• plaid_sync- 从Plaid同步银行交易
• gmail_fetch- 从Gmail获取账单
• conversational_sync- 自然语言同步界面
• conversational_status- 检查同步状态

可用命令（通过插件）

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

附加组件（可选）

独立命令行界面

对于偏好命令行界面的用户，独立命令行界面作为一个单独的 npm 包提供。请访问https://github.com/fire-la/billclaw查看安装说明。

连接 OAuth 服务器

对于自托管的 OAuth 流程，连接服务器作为一个单独的 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
• 问题反馈：https://github.com/fire-la/billclaw/issues
• 安全：请通过以下方式私下报告安全漏洞security@fire-la.dev
• npm 包：https://www.npmjs.com/org/firela