介绍
# BillClaw - Financial Data Management for OpenClaw
为 OpenClaw 提供完整的财务管理功能，采用本地优先架构。同步银行交易、从电子邮件获取账单，并导出为会计格式。
## 安全与信任
**BillClaw 是安全的开源软件，设计遵循安全第一原则。**
### 验证
- **透明化软件包**：所有 npm 软件包均为开源，并附带来源证明发布 - **可审计代码**：完整源代码可在 [GitHub](https://github.com/fire-la/billclaw) 获取 - **npm 来源证明**：将软件包与源代码链接的加密证明 - **本地优先**：您的财务数据永远不会离开您的机器 - **用户控制的凭据**：您通过自己的账户提供所有 API 凭据 - **系统钥匙串**：令牌在您平台的安全钥匙串中加密 - **显式调用**：需要明确的用户操作（`disable-model-invocation: true`）
有关详细的安全架构和验证步骤，请参阅 [SECURITY.md](./SECURITY.md)。
### 解决安全顾虑
| 顾虑 | 说明 | |---------|-------------| | **sets-process-name** | 来自传递性 npm 依赖项，而非 BillClaw 代码 | | **detect-debug-environment** | 常见的 Node.js 生态系统模式，非恶意行为 | | **API 凭据** | 功能所必需；您通过自己的账户控制它们 | | **外部软件包** | 所有软件包均为开源，且具有 npm 来源证明 |
## 所需凭据
**重要**：安装时**不需要**凭据。准备好使用特定功能时再进行配置：
| 环境变量 | 用途 | 用于 | |---------------------|---------|--------------| | `PLAID_CLIENT_ID` | Plaid API 客户端 ID | Plaid 银行同步 | | `PLAID_SECRET` | Plaid API 密钥 | Plaid 银行同步 | | `GMAIL_CLIENT_ID` | Gmail OAuth 客户端 ID | Gmail 账单获取 | | `GMAIL_CLIENT_SECRET` | Gmail OAuth 客户端密钥 | Gmail 账单获取 |
**获取凭据来源：** - **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`
## 快速开始
### 1. 安装插件
```bash npm install @firela/billclaw-openclaw ```
该插件向 OpenClaw 注册了以下工具和命令： - **工具**：`plaid_sync`、`gmail_fetch`、`conversational_sync`、`conversational_status` - **命令**：`/billclaw-setup`、`/billclaw-sync`、`/billclaw-status`、`/billclaw-config`
### 2. 配置凭据
当您准备好使用某项功能时，配置所需的凭据：
```bash # 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-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 服务器
对于自托管的 OAuth 流程，Connect 服务器可作为单独的 npm 软件包使用。有关配置详细信息，请参阅 https://github.com/fire-la/billclaw。
## 数据源
| 来源 | 描述 | 区域 | |--------|-------------|---------| | **Plaid** | 银行交易同步 | 美国、加拿大 | | **GoCardless** | 欧洲银行集成 | 欧洲 | | **Gmail** | 通过电子邮件获取账单 | 全球 |
## 存储
- **位置**：`~/.firela/billclaw/`（您的主目录） - **格式**：按月分区的 JSON 文件 - **安全性**：仅限本地存储
## 配置
配置存储在 `~/.firela/billclaw/config.json` 中：
```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 - **安全**：通过 [email protected] 私密报告安全漏洞 - **npm 软件包**：https://www.npmjs.com/org/firela