Monitors all configured model quotas and sends alerts when usage drops below or recovers above a configurable threshold, avoiding duplicate notifications.
---
name: token-monitor
description: Monitor OpenClaw token/quota usage and alert when any quota drops below a threshold (default 20%). Uses `openclaw models status` and writes only a local state file to avoid duplicate alerts. **Does not handle secrets.** **Token cost:** Script itself: 0 tokens (pure bash). Heartbeat integration: ~1k-2k tokens/hour (reading HEARTBEAT.md + executing script). Alert delivery: ~500-1k tokens/alert. **Optimization:** Use system cron instead of heartbeat to reduce to ~0 tokens (except alerts).
---
# 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
```
```
### 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
```
⚠️ Model Quota Alert (<20%):
• openai-codex Day: 0% left
• github-copilot Premium: 5% left
```
### Recovery Alert
```
✅ Quota Recovered (>=20%):
• openai-codex 5h: 100% left
```
## State File
The script maintains state in:
```
~/.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 <pct>`: Set alert threshold (overrides `QUOTA_THRESHOLD`)
- `--state-file <path>`: Set state file location (overrides `QUOTA_STATE_FILE`)
## How It Works
1. **Parse quota data**: Runs `openclaw models status` and extracts all "X% left" values
2. **Identify low quotas**: Finds all quotas below threshold
3. **Compare with previous state**: Determines new warnings and recoveries
4. **Send alerts**: Uses `openclaw cron wake` to deliver notifications
5. **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`
don't have the plugin yet? install it then click "run inline in claude" again.