✓ Verified 💻 Development ✓ Enhanced Data

Token Monitor

Monitor OpenClaw token/quota usage and alert when any quota drops below a threshold (default 20%)

Rating: 4.3 (382 reviews)
Downloads: 40,204 downloads
Version: 1.0.0

Overview

Monitor OpenClaw token/quota usage and alert when any quota drops below a threshold (default 20%)

✨Key Features

Multi-provider support: Monitors all configured providers (openai-codex, github-copilot, google-antigravity, etc.)

Multi-quota tracking: Tracks all quota types (5h, Day, Premium, Chat, etc.)

Smart alerting: Only alerts on new low-quota events (no spam)

Recovery notifications: Alerts when quota recovers above threshold

State persistence: Remembers previous warnings across runs

Complete Documentation

View Source →

Token Monitor

Monitors OpenClaw token/quota usage and outputs alerts when any quota drops below a configurable threshold (default 20%).

Features

Multi-provider support: Monitors all configured providers (openai-codex, github-copilot, google-antigravity, etc.)
Multi-quota tracking: Tracks all quota types (5h, Day, Premium, Chat, etc.)
Smart alerting: Only alerts on new low-quota events (no spam)
Recovery notifications: Alerts when quota recovers above threshold
State persistence: Remembers previous warnings across runs

Install / Update (ClawHub)

Install:

bash

clawhub install token-monitor

Update:

bash

clawhub update token-monitor

(You can also run clawhub update --all.)

Disable / Uninstall

If enabled via HEARTBEAT.md

Remove the Token Monitor section from HEARTBEAT.md (or comment it out). No further uninstall needed.

If enabled via an OpenClaw cron job

Disable/remove the cron job:

bash

openclaw cron list
openclaw cron remove <jobId>

Optional cleanup (state)

bash

rm -f ~/.openclaw/workspace/skills/token-monitor/.token-state.json

Usage

Manual Check

Run the monitoring script directly:

bash

skills/token-monitor/scripts/check-quota.sh

If installed into ~/.openclaw/skills, run:

bash

~/.openclaw/skills/token-monitor/scripts/check-quota.sh

With custom threshold (default 20%):

bash

skills/token-monitor/scripts/check-quota.sh --threshold 10

Automated Monitoring (Heartbeat)

Add to HEARTBEAT.md for periodic checks:

markdown

## Token Monitor (every ~60min, rotate)

Check model quotas and alert if below threshold.

**Instructions:**
1. Run `output=$(skills/token-monitor/scripts/check-quota.sh 2>&1)`
2. If output non-empty → send wake event with output text
3. If empty → all quotas OK, continue silently

**Rotate check:** Only run every ~4th heartbeat (once/hour if heartbeat is 15min)

**Example integration:**

bash output=$(skills/token-monitor/scripts/check-quota.sh 2>&1) if [[ -n "$output" ]]; then openclaw cron wake --text "$output" --mode now fi

text

Automated Monitoring (Cron Job)

Create a dedicated cron job for precise scheduling:

bash

openclaw cron add --schedule "*/30 * * * *" \
  --payload '{"kind":"systemEvent","text":"Run quota monitor: skills/token-monitor/scripts/check-quota.sh"}' \
  --name "Token Monitor (30min)"

Output

Low Quota Alert

text

⚠️ Model Quota Alert (<20%):
• openai-codex Day: 0% left
• github-copilot Premium: 5% left

Recovery Alert

text

✅ Quota Recovered (>=20%):
• openai-codex 5h: 100% left

State File

The script maintains state in:

text

~/.openclaw/workspace/skills/token-monitor/.token-state.json

Example state:

json

{
  "warned": [
    "openai-codex Day: 0% left",
    "github-copilot Premium: 5% left"
  ],
  "current": [
    "openai-codex:5h=100",
    "openai-codex:Day=0",
    "github-copilot:Premium=5",
    "github-copilot:Chat=100"
  ],
  "lastCheck": "2026-02-15T09:30:00Z",
  "threshold": 20
}

Configuration

Environment Variables

QUOTA_THRESHOLD: Alert threshold percentage (default: 20)
QUOTA_STATE_FILE: Path to state file (default: ~/.openclaw/workspace/skills/token-monitor/.token-state.json)

Script Arguments

--threshold : Set alert threshold (overrides QUOTA_THRESHOLD)
--state-file : Set state file location (overrides QUOTA_STATE_FILE)

How It Works

Parse quota data: Runs openclaw models status and extracts all "X% left" values
Identify low quotas: Finds all quotas below threshold
Compare with previous state: Determines new warnings and recoveries
Send alerts: Uses openclaw cron wake to deliver notifications
Update state: Saves current state for next run

Dependencies

openclaw CLI (models status, cron wake)
jq (JSON parsing)
bash 4.0+

Troubleshooting

No alerts sent:

Check that quota is actually below threshold: openclaw models status
Verify state file permissions: cat ~/.openclaw/workspace/skills/token-monitor/.token-state.json
Run script manually to see output: skills/token-monitor/scripts/check-quota.sh

Duplicate alerts:

State file may be corrupted or deleted
Check state file for warned array: jq .warned ~/.openclaw/workspace/skills/token-monitor/.token-state.json

Script fails:

Ensure jq is installed: jq --version
Check script permissions: ls -l skills/token-monitor/scripts/check-quota.sh
Run with verbose output: bash -x skills/token-monitor/scripts/check-quota.sh

Installation

Terminal bash


openclaw install token-monitor

Copied!

💻Code Examples

Disable/remove the cron job:

disableremove-the-cron-job.sh

openclaw cron list
openclaw cron remove <jobId>

skills/token-monitor/scripts/check-quota.sh --threshold 10

skillstoken-monitorscriptscheck-quotash---threshold-10.txt

### Automated Monitoring (Heartbeat)

Add to `HEARTBEAT.md` for periodic checks:

Example integration:

example-integration.sh

output=$(skills/token-monitor/scripts/check-quota.sh 2>&1)
if [[ -n "$output" ]]; then
  openclaw cron wake --text "$output" --mode now
fi

--name "Token Monitor (30min)"

---name-token-monitor-30min.txt

## Output

### Low Quota Alert

• openai-codex 5h: 100% left

-openai-codex-5h-100-left.txt

## State File

The script maintains state in:

example.md

## Token Monitor (every ~60min, rotate)

Check model quotas and alert if below threshold.

**Instructions:**
1. Run `output=$(skills/token-monitor/scripts/check-quota.sh 2>&1)`
2. If output non-empty → send wake event with output text
3. If empty → all quotas OK, continue silently

**Rotate check:** Only run every ~4th heartbeat (once/hour if heartbeat is 15min)

**Example integration:**

example.sh

openclaw cron add --schedule "*/30 * * * *" \
  --payload '{"kind":"systemEvent","text":"Run quota monitor: skills/token-monitor/scripts/check-quota.sh"}' \
  --name "Token Monitor (30min)"

example.txt

⚠️ Model Quota Alert (<20%):
• openai-codex Day: 0% left
• github-copilot Premium: 5% left

example.json

{
  "warned": [
    "openai-codex Day: 0% left",
    "github-copilot Premium: 5% left"
  ],
  "current": [
    "openai-codex:5h=100",
    "openai-codex:Day=0",
    "github-copilot:Premium=5",
    "github-copilot:Chat=100"
  ],
  "lastCheck": "2026-02-15T09:30:00Z",
  "threshold": 20
}