openrouter-usage

获取实时 OpenRouter 使用总量和每个模型的历史支出。当用户询问使用情况、支出、成本细分或 OpenRouter 统计信息时使用。不适用于系统健康状况或非 LLM 指标。

# OpenRouter Usage Monitor

## What this skill does
Retrieves OpenRouter usage and cost data via:
- **Live totals (Today / Week / Month)** from `/auth/key`
- **Historical per-model breakdown** from `/activity` (completed UTC days only)

---
## How to run (recommended)
Set environment variables (recommended) or create a `credentials.env` file:

```bash
export OPENROUTER_API_KEY=your_key_here
export OPENROUTER_MGMT_KEY=your_mgmt_key_here  # optional, enables model breakdown
```

Then execute: `python3 scripts/stats.py`

Alternatively, create `credentials.env` in the skill directory:
```
OPENROUTER_API_KEY=your_key_here
OPENROUTER_MGMT_KEY=your_mgmt_key_here
```

---
## Fallback method (no Python)
If Python is unavailable, query endpoints directly:

**Live totals**
curl -sS -H "Authorization: Bearer $OPENROUTER_API_KEY"
https://openrouter.ai/api/v1/auth/key

**Per-model activity (7d)**
curl -sS -H "Authorization: Bearer $OPENROUTER_MGMT_KEY"
https://openrouter.ai/api/v1/activity
---
## Configuration
**Required:**
- `OPENROUTER_API_KEY` - Required for real-time usage totals and balance

**Optional:**
- `OPENROUTER_MGMT_KEY` - Enables per-model spend breakdown from activity endpoint

Credentials can be provided via:
1. Environment variables (recommended for security)
2. `credentials.env` file in skill directory (fallback)

---
## Output format
💰 OpenRouter Usage
Today: $X.XX* | Week: $X.XX | Month: $X.XX
Balance: $X.XX / $X.XX

Recent Models (7d):
• model-name: $X.XX (N)
...
`*` indicates live totals that may not yet appear in model breakdowns.
---

## Edge cases
- `/activity` only returns completed UTC days.
- Today’s spend may appear in totals but not per-model data until next UTC rollover.
- Invalid keys → 401/403.
- Rate limiting → 429.
- Network failures should be retried or surfaced.

---

## 中文说明

# OpenRouter 使用情况监控

## 此技能的作用
通过以下方式获取 OpenRouter 的使用情况和成本数据：
- 来自 `/auth/key` 的**实时总量（今日 / 本周 / 本月）**
- 来自 `/activity` 的**历史的每个模型细分**（仅限已完成的 UTC 日）

---
## 如何运行（推荐）
设置环境变量（推荐）或创建一个 `credentials.env` 文件：

```bash
export OPENROUTER_API_KEY=your_key_here
export OPENROUTER_MGMT_KEY=your_mgmt_key_here  # optional, enables model breakdown
```

然后执行：`python3 scripts/stats.py`

或者，在技能目录中创建 `credentials.env`：
```
OPENROUTER_API_KEY=your_key_here
OPENROUTER_MGMT_KEY=your_mgmt_key_here
```

---
## 回退方法（无 Python）
如果 Python 不可用，直接查询接口：

**实时总量**
curl -sS -H "Authorization: Bearer $OPENROUTER_API_KEY"
https://openrouter.ai/api/v1/auth/key

**每个模型的活动（7 天）**
curl -sS -H "Authorization: Bearer $OPENROUTER_MGMT_KEY"
https://openrouter.ai/api/v1/activity
---
## 配置
**必需：**
- `OPENROUTER_API_KEY` - 获取实时使用总量和余额所必需

**可选：**
- `OPENROUTER_MGMT_KEY` - 启用来自 activity 接口的每个模型支出细分

凭据可通过以下方式提供：
1. 环境变量（出于安全考虑推荐）
2. 技能目录中的 `credentials.env` 文件（回退方式）

---
## 输出格式
💰 OpenRouter Usage
Today: $X.XX* | Week: $X.XX | Month: $X.XX
Balance: $X.XX / $X.XX

Recent Models (7d):
• model-name: $X.XX (N)
...
`*` 表示可能尚未出现在模型细分中的实时总量。
---

## 边缘情况
- `/activity` 只返回已完成的 UTC 日。
- 今日支出可能出现在总量中，但在下一次 UTC 跨日之前不会出现在每个模型的数据中。
- 无效的密钥 → 401/403。
- 速率限制 → 429。
- 网络故障应当重试或予以提示。