Monzo

# Monzo Banking Skill

访问您的 Monzo 银行账户以查询余额、查看交易、管理储蓄罐，并向您的 Monzo 应用发送通知。

## 先决条件

在设置此技能之前，您需要：

- **一个 Monzo 账户**（英国个人、联名或商业账户） - **Monzo 应用**已安装在您的手机上（用于 SCA 批准） - 运行中的 **OpenClaw** 并拥有工作区访问权限 - **标准工具**：`curl`、`jq`、`openssl`、`bc`（在大多数 Linux 系统上预装）

## 快速开始 (TL;DR)

```bash # 1. Set the MONZO_KEYRING_PASSWORD env var (see "Setting the Password" below)

# 2. Create OAuth client at https://developers.monzo.com/ # - Set Confidentiality: Confidential # - Set Redirect URL: http://localhost

# 3. Run setup scripts/setup.sh

# 4. Approve in Monzo app when prompted, then: scripts/setup.sh --continue

# 5. Test it scripts/balance.sh ```

---

## 详细设置指南

### 步骤 1：设置加密密码

`MONZO_KEYRING_PASSWORD` 环境变量用于加密存储您的 Monzo 凭证。请选择一个强且唯一的密码，并且不要丢失它——如果您将来移动或恢复技能，将需要它。

有几种方法可以提供此变量。选择适合您设置的方式：

**选项 A：OpenClaw 技能配置**（最简单）

添加到您的 OpenClaw 配置中（例如 `openclaw.json`）：

```json5 { skills: { entries: { "monzo": { enabled: true, env: { "MONZO_KEYRING_PASSWORD": "choose-a-secure-password-here" } } } } } ```

然后重启：`openclaw gateway restart`

> **注意：** 这会将密码以明文形式存储在配置文件中。确保该文件具有严格的权限（`chmod 600`）并且未提交到版本控制中。

**选项 B：Shell 环境**（使密码不保留在配置文件中）

添加到您的 Shell 配置文件（`~/.bashrc`、`~/.zshrc` 等）中：

```bash export MONZO_KEYRING_PASSWORD="choose-a-secure-password-here" ```

然后重启您的 Shell 和 OpenClaw。

**选项 C：systemd EnvironmentFile**（用于服务器部署）

创建一个密钥文件（例如 `/etc/openclaw/monzo.env`）：

``` MONZO_KEYRING_PASSWORD=choose-a-secure-password-here ```

设置权限：`chmod 600 /etc/openclaw/monzo.env`

在您的 systemd 单元文件中通过 `EnvironmentFile=/etc/openclaw/monzo.env` 引用它。

**选项 D：密码管理器 / 密钥管理器**

使用您首选的密钥工具在运行时注入环境变量。任何在进程环境中设置 `MONZO_KEYRING_PASSWORD` 的方法都可以使用。

### 步骤 2：创建 Monzo OAuth 客户端

1. 访问 **https://developers.monzo.com/** 并使用您的 Monzo 账户登录 2. 点击 **"Clients"** → **"New OAuth client"** 3. 填写： - **Name**：`OpenClaw`（或您喜欢的名称） - **Logo URL**：*（留空）* - **Redirect URLs**：`http://localhost` ← 必须完全一致，末尾不要有斜杠 - **Description**：*（留空）* - **Confidentiality**：**Confidential** ← ⚠️ 重要！这会启用刷新令牌 4. 点击 **Submit** 5. 记下您的 **Client ID** (`oauth2client_...`) 和 **Client Secret** (`mnzconf....`)

### 步骤 3：运行设置向导

```bash scripts/setup.sh ```

向导将会： 1. 询问您的 Client ID 和 Client Secret 2. 为您提供一个需要在浏览器中打开的授权 URL 3. 要求您粘贴重定向 URL 回来 4. 将代码交换为访问令牌 5. 保存加密的凭证

**替代方案：非交互模式**（适用于自动化或代理）： ```bash scripts/setup.sh --non-interactive \ --client-id oauth2client_xxx \ --client-secret mnzconf.xxx \ --auth-code eyJ... ```

### 步骤 4：在 Monzo 应用中批准 (SCA)

⚠️ **此步骤是必须的！** Monzo 要求强客户验证 (SCA)。

1. 打开手机上的 **Monzo 应用** 2. 查找关于 "API access" 或新连接的通知 3. **点击批准**

如果您没有看到通知： - 前往 **Account → Settings → Privacy & Security → Manage connected apps** - 找到并批准您的客户端

批准后，完成设置： ```bash scripts/setup.sh --continue ```

### 步骤 5：验证是否正常工作

```bash # Check authentication scripts/whoami.sh

# Check your balance scripts/balance.sh ```

您应该能看到您的账户信息和当前余额。完成啦！🎉

---

## 给代理的说明

本部分告诉代理如何有效使用此技能。

### 何时使用此技能

当用户询问以下内容时使用此技能： - **余额**："How much money do I have?", "What's my balance?"（我有多少钱？我的余额是多少？） - **交易**："What did I spend on X?", "Show recent transactions"（我在 X 上花了多少钱？显示最近的交易） - **支出分析**："How much did I spend on coffee this month?"（我这个月在咖啡上花了多少钱？） - **储蓄**："How much is in my savings?", "Move £X to my holiday pot"（我的储蓄里有多少钱？将 X 英镑转入我的假期罐） - **通知**："Send a reminder to my Monzo app"（向我的 Monzo 应用发送一个提醒）

### 常见模式

```bash # "How much money do I have?" scripts/balance.sh

# "Show me recent transactions" / "What did I spend?" scripts/transactions.sh # All available, newest first

# "Show me my last 5 transactions" scripts/transactions.sh --limit 5 # 5 most recent

# "What did I spend this week?" scripts/transactions.sh --since 7d

# "How much did I spend on coffee this month?" scripts/transactions.sh --search coffee --since 30d

# "What are my savings pots?" scripts/pots.sh

# "Put £50 in my holiday fund" scripts/pots.sh deposit pot_XXXXX 5000 # Amount in pence!

# "Send a reminder to my phone" scripts/feed.sh --title "Don't forget!" --body "Check the gas meter" ```

### 给代理的重要提示

1. **金额以便士为单位**：£50 = 5000，£1.50 = 150 2. **日期可以是相对的**：`--since 7d` 表示过去 7 天 3. **默认使用人类可读的输出**（不要使用 `--json` 标志） 4. **罐 ID**：在进行存取款之前，请先使用 `scripts/pots.sh` 获取罐 ID 5. **多个账户**：用户可能拥有个人、联名和商业账户。默认是个人账户。使用 `scripts/whoami.sh` 查看所有账户。

### 错误处理

如果您看到 `forbidden.insufficient_permissions`： - 告知用户检查他们的 Monzo 应用并批准 API 访问 - 然后运行 `scripts/setup.sh --continue`

如果您看到 `MONZO_KEYRING_PASSWORD not set`： - 环境变量在进程环境中不可用 - 指导用户使用设置指南步骤 1 中的一种方法进行设置

---

## 脚本参考

### balance - 检查账户余额

```bash scripts/balance.sh # Default account scripts/balance.sh acc_... # Specific account scripts/balance.sh --json # JSON output ```

**输出：** ``` Current Balance: £1,234.56 Total (with pots): £2,500.00 Spent today: £12.34 ```

### transactions - 交易历史

获取 **所有可用的交易**（分页显示），**最新的显示在最前面**。

```bash scripts/transactions.sh # All transactions, newest first scripts/transactions.sh --limit 10 # 10 most recent scripts/transactions.sh --since 7d # Last 7 days only scripts/transactions.sh --since 2026-01-01 # Since specific date scripts/transactions.sh --search coffee # Search by merchant/description/notes scripts/transactions.sh --search "Pret" --since 30d # Combined filters scripts/transactions.sh --id tx_... # Get specific transaction scripts/transactions.sh --json # JSON output ```

**输出：** ``` DATE AMOUNT DESCRIPTION CATEGORY ============ ========== =================================== =============== 2026-01-29 -£3.50 Pret A Manger eating_out 2026-01-29 -£12.00 TfL transport 2026-01-28 -£45.23 Tesco groceries

Total: 3 transaction(s) ```

### pots - 储蓄管理

```bash scripts/pots.sh # List all pots scripts/pots.sh list --json # JSON output scripts/pots.sh deposit pot_... 5000 # Deposit £50 (5000 pence) scripts/pots.sh withdraw pot_... 2000 # Withdraw £20 (2000 pence) ```

**输出（列表）：** ``` NAME BALANCE GOAL ID ========================= ============ ============ ==================== Holiday Fund £450.00 £1,000.00 pot_0000... Emergency £2,000.00 £3,000.00 pot_0001... ```

### feed - 发送应用通知

```bash scripts/feed.sh --title "Reminder" # Simple notification scripts/feed.sh --title "Alert" --body "Details here" # With body scripts/feed.sh --title "Link" --url "https://..." # With tap action ```

### whoami - 检查认证状态

```bash scripts/whoami.sh # Show auth status and accounts scripts/whoami.sh --account-id # Just the default account ID scripts/whoami.sh --json # JSON output ```

### receipt - 将收据附加到交易

```bash scripts/receipt.sh create tx_... --merchant "Shop" --total 1234 --item "Thing:1234" scripts/receipt.sh get ext_... scripts/receipt.sh delete ext_... ```

### webhooks - 管理 Webhooks（高级）

```bash scripts/webhooks.sh list scripts/webhooks.sh create https://your-server.com/webhook scripts/webhooks.sh delete webhook_... ```

---

## 故障排除

### "forbidden.insufficient_permissions"

**最常见的问题！** Monzo 需要应用批准 (SCA)。

**修复方法：** 1. 打开 Monzo 应用 → 检查通知 → 批准 2. 或者：Account → Settings → Privacy & Security → Manage connected apps → 批准 3. 运行：`scripts/setup.sh --continue`

### "MONZO_KEYRING_PASSWORD not set"

环境变量在进程环境中不可用。

**修复方法：** 使用设置指南步骤 1 中描述的任意一种方法设置 `MONZO_KEYRING_PASSWORD`，然后重启 OpenClaw。

### "Authorization code has been used"

每个授权码只能使用一次。重新开始： ```bash scripts/setup.sh --reset ```

### "No refresh token received"

您的 OAuth 客户端未设置为 "Confidential"。创建一个新客户端并将 Confidentiality 设置为 Confidential，然后： ```bash scripts/setup.sh --reset ```

### "Credentials file not found"

请先运行设置： ```bash scripts/setup.sh ```

### "Failed to decrypt credentials"

`MONZO_KEYRING_PASSWORD` 错误。请检查您的配置是否与设置期间使用的密码一致。

---

## 安全说明

- 凭证 **静态加密** (AES-256-CBC) - 加密密钥是您的 `MONZO_KEYRING_PASSWORD` - 访问令牌会自动刷新（无需手动干预） - 文件权限设置为 600（仅限所有者） - 所有 API 调用均使用 HTTPS - 不记录敏感数据

---

## 文件

``` skills/monzo/ ├── SKILL.md # This documentation └── scripts/ ├── lib/monzo.sh # Shared library ├── setup # OAuth setup wizard ├── whoami # Validate authentication ├── balance # Check balance ├── transactions # Transaction history ├── pots # Savings pots ├── feed # App notifications ├── receipt # Receipt management └── webhooks # Webhook management ```

**凭证：** `~/.openclaw/credentials/monzo.json`（已加密，或在较旧的安装中为 `~/.clawdbot/credentials/monzo.json`）

---

## API 覆盖范围

| 功能 | 脚本 | |---------|---------| | 身份验证 | setup, whoami | | 余额 | balance | | 交易 | transactions | | 罐（储蓄） | pots | | 动态（通知） | feed | | 收据 | receipt | | Webhooks | webhooks |