What this skill does

--- 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`