Skill: donovanpankratz-del/openclaw-cost-governor (version 1.0.0)

--- name: cost-governor version: 1.0.0 description: Pre-flight cost estimation for subagent spawns and approval gates. Prevents API overspend and surprise billing. Budget control for sessions_spawn calls. Daily spend tracking. Essential for multi-agent OpenClaw deployments. homepage: https://clawhub.com changelog: Initial release - Pre-flight gates, historical multipliers, spend tracking metadata: openclaw: emoji: "💰" requires: bins: [] os: - linux - darwin - win32 --- # Cost Governor - Subagent Cost Control Pre-flight cost checks before spawning subagents. Tracks spend. Gates expensive operations. **Prevents surprise $300+ bills.** ## Files Included - `SKILL.md` — This file (agent instructions) - `README.md` — Human-readable setup guide - `cost-tracking-template.md` — Copy this to `notes/cost-tracking.md` to get started - `lib/cost-tracker.js` — Core estimation and logging library - `bin/cost-summary.js` — CLI: daily/monthly spend summary ## Problem Solved You spawn a subagent for "research passive income ideas" on Opus. 30 minutes later: $12 gone. This skill estimates cost **before** execution, requires approval for expensive tasks (>$0.50), and tracks all spend. ## When to Use - **Before spawning any subagent** — estimate cost, log it - **Daily spend review** — summarize costs vs budget - **Post-task reconciliation** — compare estimated vs actual ## Core Rules 1. **Every subagent spawn >$0.50 estimated requires explicit user approval** 2. **All spawns get logged** to `$WORKSPACE/notes/cost-tracking.md` 3. **Estimates use multipliers** from historical data (see Cost Model) 4. **No silent expensive operations** — always surface cost before execution ## Cost Model Based on historical data from `cost-tracking.md`: | Task Type | Base Estimate | Multiplier | Effective Estimate | |-----------|--------------|------------|-------------------| | Creative (open-ended) | Token estimate | **7.5x** | Apply to all creative tasks | | Research (bounded) | Token estimate | **3x** | Web search + synthesis | | Technical (structured) | Token estimate | **2x** | Code, config, structured output | | Simple (template) | Token estimate | **1.5x** | Fill-in, short responses | **Model cost rates (approximate per 1K tokens):** - Claude Opus: ~$0.075 input / $0.375 output - Claude Sonnet: ~$0.003 input / $0.015 output - GPT-4: ~$0.03 input / $0.06 output - Grok 4.1 Fast Reasoning: ~$0.003 input / $0.015 output - Claude Haiku 4.5: ~$0.0008 input / $0.004 output ### Estimation Formula ``` estimated_cost = (estimated_output_tokens / 1000) * output_rate * task_multiplier ``` **Example:** - Task: Creative writing (5000 tokens estimated on Opus) - Calculation: (5000 / 1000) * $0.375 * 7.5 = **$14.06** - Action: **Require approval** (>$0.50 threshold) ## Setup 1. Create cost tracking file: ```bash mkdir -p ~/.openclaw/workspace/notes touch ~/.openclaw/workspace/notes/cost-tracking.md ``` 2. Add header to `cost-tracking.md`: ```markdown # Cost Tracking Log | Date | Task | Model | Est. | Actual | Ratio | Notes | |------|------|-------|------|--------|-------|-------| ``` 3. Set your daily budget (optional): ```bash echo "DAILY_BUDGET=20.00" >> ~/.openclaw/workspace/.env ``` ## Usage ### Pre-Flight Check (Before Spawning) ``` User: "Research passive income methods" Agent: Checking cost... Estimated $3.50 (Research task, Opus, ~3K tokens * 3x multiplier). Approve? User: Yes Agent: [spawns, logs to cost-tracking.md] ``` ### Daily Spend Dashboard Run manually or via cron: ```markdown ## Daily Spend — 2026-02-21 | Task | Model | Est. | Actual | Ratio | |------|-------|------|--------|-------| | PassiveIncomeResearch | Opus | $3.50 | $4.20 | 1.2x | | AIHardwareResearch | Sonnet | $0.80 | $0.65 | 0.8x | **Total:** $4.30 est / $4.85 actual **Budget remaining:** $15.15 / $20.00 daily ``` ### Post-Task Reconciliation After each subagent completes: 1. Check actual cost (if available via `/status`) 2. Log to `cost-tracking.md` 3. Update multipliers if ratio is consistently off ## Triggers - **Pre-spawn gate**: Before `sessions_spawn`, estimate and log. If >$0.50, ask user. - **Cron (daily, optional)**: Summarize daily spend, flag overruns. - **Post-task**: Log actual cost, update multipliers if data available. ## Approval Gate Flow 1. Estimate cost using model + task type + multiplier 2. If estimate ≤ $0.50 → proceed, log silently 3. If estimate > $0.50 → present estimate to user, wait for "approve" / "yes" 4. Log decision (approved/rejected/modified) to tracking file ## Budget Alerts Set a daily budget cap. When spend exceeds it, the agent stops spawning and notifies you. **Setup:** Add to your workspace config or mention it in system prompt: > "Daily API budget: $XX. Stop spawning subagents if estimated total exceeds this." **Cron-based daily summary (optional):** Add to your cron: ```bash # Daily cost summary at 11 PM 0 23 * * * node ~/.openclaw/workspace/skills/cost-governor/bin/cost-summary.js --daily ``` ## Anti-Patterns (What NOT to Do) - ❌ Spawning Opus for simple lookups (use Sonnet or Haiku) - ❌ Open-ended creative tasks without cost ceiling ("write a novel") - ❌ Multiple subagents when one suffices - ❌ Skipping post-task reconciliation - ❌ Ignoring consistent ratio mismatches (update multipliers!) ## Advanced: Custom Multipliers Edit multipliers in your cost-tracking.md header: ```markdown ## Multipliers (Updated 2026-02-21) - Creative: 10x (our tasks run long) - Research: 2.5x (bounded queries) ``` Agent reads these on each check. ## Integration with Other Skills - **sessions_spawn**: Always run cost check before spawning - **AGENTS.md**: Log cost in agent entry ("Last used: $X.XX") - **Cron jobs**: Wrap expensive recurring tasks with cost gates ## Troubleshooting **Q: Estimates are consistently off** A: Update multipliers in cost-tracking.md based on actual ratios. **Q: How do I get actual costs?** A: Use `/status` after subagent completes, or check provider dashboard. ## Why This Matters Real story from r/LocalLLM (Jan 2026): > "Left my OpenClaw agent running overnight. Spawned 8 research subagents on Opus. Woke up to $340 API bill. This skill would've saved me." Don't be that person. --- **Author:** OpenClaw Community **License:** MIT **Requires:** OpenClaw with subagent support, `notes/` directory


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)