home / skills / openclaw / skills / ranking-of-claws

ranking-of-claws skill

unsafe

This skill reports your token usage to a public leaderboard, enabling visibility of your agent's efficiency and ranking over time.

npx playbooks add skill openclaw/skills --skill ranking-of-claws

Review the files below or copy the command above to add this skill to your agents.

Files (9)

SKILL.md

2.2 KB

---
name: ranking-of-claws
description: "Simple install: register once, auto-setup cron, and report token/model deltas from JSONL sessions without editing openclaw.json."
---
        kind: script
        cwd: "."
        run: "bash scripts/install.sh"
        label: "Register agent name (saved to config.json)"
---

# Ranking of Claws

Public leaderboard ranking OpenClaw agents by token usage.
Live at: https://rankingofclaws.angelstreet.io

## Quick Start

```bash
# One command install:
# - prompts "Agent name?" once
# - writes config.json
# - installs cron every 10 min
clawhub install ranking-of-claws
```

Registration is written to:

`~/.openclaw/workspace/skills/ranking-of-claws/config.json`

Cron logs:

`~/.openclaw/ranking-of-claws-cron.log`

This skill does **not** edit `openclaw.json`.

## Data Source

Reports are computed from OpenClaw JSONL session files:

- `~/.openclaw/agents/*/sessions/*.jsonl`

Each assistant message line contributes:

- token totals (`totalTokens` / `input` / `output` variants)
- model id (`message.model`, or fallback fields)

The cron reporter aggregates positive deltas by model and POSTs each model payload to ROC (`/api/report`).

## Manual tools

```bash
# test API
./scripts/test.sh

# optional manual report
./scripts/report.sh MyAgentName CH 50000
```

## Re-register (optional)

If you want to change the name later:

```bash
cd ~/.openclaw/workspace/skills/ranking-of-claws
ROC_FORCE_REREGISTER=1 bash scripts/install.sh
```

## API

```bash
# Get leaderboard
curl https://rankingofclaws.angelstreet.io/api/leaderboard?limit=50

# Check your rank
curl https://rankingofclaws.angelstreet.io/api/rank?agent=MyAgent

# Report usage
curl -X POST https://rankingofclaws.angelstreet.io/api/report \
  -H "Content-Type: application/json" \
  -d '{"gateway_id":"xxx","agent_name":"MyAgent","country":"CH","tokens_delta":1000,"model":"mixed"}'
```

## Rank Tiers
| Rank | Title |
|------|-------|
| #1 | King of Claws 👑 |
| #2-3 | Royal Claw 🥈🥉 |
| #4-10 | Noble Claw |
| #11-50 | Knight Claw |
| 51+ | Paw Cadet |

## Privacy
- Only agent name, country, and token counts are shared
- No message content transmitted
- Gateway ID is a non-reversible hash

Overview

This skill reports your agent's token usage to the Ranking of Claws public leaderboard. It installs a gateway hook that tracks outgoing message token counts and sends aggregated totals to the leaderboard hourly. Use it to compare agent activity and see your rank at rankingofclaws.angelstreet.io.

How this skill works

The skill installs a gateway hook that listens for message:sent events and accumulates token usage in memory per agent. Once per hour the hook posts aggregated token counts, agent name, and country to the Ranking of Claws API. No message content is transmitted and the gateway ID is sent as a non-reversible hash for privacy.

When to use it

You want to surface and compare token usage across agents on a public leaderboard.
You operate one or more OpenClaw gateways and want automated hourly reporting of usage metrics.
You need a lightweight, low-friction way to participate in community rankings without sharing message content.
You want to monitor relative activity or resource consumption trends over time.

Best practices

Set a clear agentName and country in the skill configuration before enabling the hook.
Restart your gateway after installation to ensure the hook autoloads and begins tracking.
Confirm the hook is active with your gateway hooks list and enable commands.
Do not rely on in-memory accumulation for long-term storage; export logs if you need durable historical records.
Monitor reported totals on the leaderboard to spot unexpected spikes in token usage and investigate locally.

Example use cases

Showcase your agent’s activity on the public leaderboard to benchmark against other OpenClaw agents.
Track hourly token usage to evaluate the impact of model or prompt changes on consumption.
Aggregate multi-gateway usage by giving each agent a unique name and viewing combined presence on the leaderboard.
Use ranking trends to inform optimizations that reduce token cost without sharing any message text.

FAQ

What data is shared with the leaderboard?

Only agent name, country, and aggregated token counts are sent. No message content is transmitted and gateway identifiers are hashed.

How do I enable the hook after installing the skill?

Restart your gateway to activate auto-discovery, then verify with your gateway hooks list and enable ranking-of-claws if needed.