openrouter-analytics

通过 API 查看 OpenRouter 使用情况、分析和故障排除数据。当用户请求支出/使用情况监控、活动趋势、每个密钥管理报告或对特定请求 ID 进行深入调查（延迟、提供商回退、完成原因、令牌/成本细分）时使用。

# OpenRouter Analytics

Use this skill to pull **management-level usage data** and **request-level troubleshooting details** from OpenRouter.

## Quick Start

Run from this skill folder:

```bash
cd ~/clawd/skills/openrouter-analytics
```

Management key operations (set `OPENROUTER_MANAGEMENT_KEY`):

```bash
python3 scripts/openrouter_analytics.py activity --limit 20
python3 scripts/openrouter_analytics.py activity --date 2026-02-18
python3 scripts/openrouter_analytics.py activity --from 2026-02-01 --to 2026-02-18 --summary --csv /tmp/activity.csv
python3 scripts/openrouter_analytics.py credits
python3 scripts/openrouter_analytics.py keys --limit 50 --summary
python3 scripts/openrouter_analytics.py report --from 2026-02-01 --to 2026-02-18 --format markdown
```

Request-level troubleshooting (set `OPENROUTER_API_KEY`):

```bash
python3 scripts/openrouter_analytics.py generation --id <generation_id>
```

Use `--raw` on any command to print full JSON.

## Workflow

1. **Check macro activity**
   - Run `activity` for daily spend/traffic patterns.
2. **Check account-level usage**
   - Run `credits` to review consumed vs remaining credits.
3. **Find key-level consumers**
   - Run `keys` to identify which keys are driving usage.
4. **Investigate incidents**
   - Run `generation --id ...` for detailed logs on one request (latency, fallback providers, finish reason, token and cost details).

## Notes

- `activity`, `credits`, `keys`, and `report` require a **Management API key**.
- `generation` uses a standard **OpenRouter API key** and requires the request `id`.
- The script auto-loads `~/.openclaw/.env` and current-directory `.env` before execution.
- Use `--retries` and `--timeout` to tune robustness under transient API/network issues.
- Keep generation IDs in your application logs to support reliable post-incident analysis.

## Resources

- Endpoint reference and field guide: `references/endpoints.md`
- CLI helper script: `scripts/openrouter_analytics.py`

---

## 中文说明

# OpenRouter Analytics

使用此技能从 OpenRouter 拉取**管理级使用数据**和**请求级故障排除详情**。

## 快速开始

在此技能文件夹中运行：

```bash
cd ~/clawd/skills/openrouter-analytics
```

管理密钥操作（设置 `OPENROUTER_MANAGEMENT_KEY`）：

```bash
python3 scripts/openrouter_analytics.py activity --limit 20
python3 scripts/openrouter_analytics.py activity --date 2026-02-18
python3 scripts/openrouter_analytics.py activity --from 2026-02-01 --to 2026-02-18 --summary --csv /tmp/activity.csv
python3 scripts/openrouter_analytics.py credits
python3 scripts/openrouter_analytics.py keys --limit 50 --summary
python3 scripts/openrouter_analytics.py report --from 2026-02-01 --to 2026-02-18 --format markdown
```

请求级故障排除（设置 `OPENROUTER_API_KEY`）：

```bash
python3 scripts/openrouter_analytics.py generation --id <generation_id>
```

在任意命令上使用 `--raw` 可打印完整 JSON。

## 工作流程

1. **查看宏观活动**
   - 运行 `activity` 查看每日支出/流量模式。
2. **查看账户级使用情况**
   - 运行 `credits` 审查已消耗与剩余的额度。
3. **找出密钥级消耗者**
   - 运行 `keys` 识别哪些密钥在驱动使用量。
4. **调查事件**
   - 运行 `generation --id ...` 查看单个请求的详细日志（延迟、回退提供商、完成原因、令牌和成本细节）。

## 注意事项

- `activity`、`credits`、`keys` 和 `report` 需要**管理 API 密钥**。
- `generation` 使用标准的 **OpenRouter API 密钥**，并需要请求 `id`。
- 脚本在执行前会自动加载 `~/.openclaw/.env` 和当前目录下的 `.env`。
- 使用 `--retries` 和 `--timeout` 在出现瞬时 API/网络问题时调优稳健性。
- 将 generation ID 保留在应用日志中，以支持可靠的事后分析。

## 资源

- 端点参考和字段指南：`references/endpoints.md`
- CLI 辅助脚本：`scripts/openrouter_analytics.py`