Cost Optimizer

Smart cost optimization skill for OpenClaw. Reduces API costs by 70-97% through intelligent model routing, session management, output efficiency, and free model usage. Includes 29 executable scripts for auditing, monitoring, backup/restore, health checks, and automated reporting. Walks user through setup on first activation.

# Cost Optimizer v7 — Smart API Cost Reduction

This skill helps reduce your OpenClaw API costs by 70-97% through intelligent model routing, session management, and response efficiency.

> **New to this skill?** Read `GUIDE.md` for installation instructions, requirements, example outputs from every script, and common workflows.

## What's Included

| Category | Files | Purpose |
|----------|-------|---------|
| Agent instructions | `SKILL.md` (this file) | 13 chapters of cost optimization logic |
| User guide | `GUIDE.md` | Requirements, installation, example outputs, workflows |
| References | `references/` (2 files) | Model pricing card, config templates |
| Scripts | `scripts/` (29 files) | Audit, monitor, backup, health check, reporting |
| Presets | `presets/` (5 files) | Ready-to-apply configs: solo-coder, writer, researcher, zero-budget, agency-team |
| Metadata | `VERSION`, `CHANGELOG.md` | Version tracking and update history |

### Requirements

- OpenClaw 2026.3.x+, Node.js v18+, bash, curl
- Optional: OpenRouter API key (for free models), webhook URL (for reports)

### Quick Start

```
# Install
cd ~/.openclaw/workspace/skills/
unzip cost-optimizer.zip
chmod +x cost-optimizer/scripts/*.sh

# Audit current costs
bash cost-optimizer/scripts/cost-audit.sh

# Interactive setup
Tell your agent: /cost-setup
```

## SETUP FLOW (Run on first activation)

When this skill is first activated or user says "/cost-setup", walk through these steps. Ask permission at each step before making changes:

**Step 1: Budget Target**
Ask: "What's your monthly budget target? Options: Ultra-low ($0-5/mo), Low ($5-30/mo), Medium ($30-100/mo), Flexible (no hard limit but minimize waste)"
Save their answer to memory/cost-preferences.md

**Step 2: Free Models**
Ask: "Want me to add free OpenRouter models to your config? These cost $0.00 per request and handle 60-80% of simple tasks well. I'll add: DeepSeek V3 Free, Llama 4 Scout Free, Qwen 3 Free, Gemma 3 Free, Mistral Small Free. Approve? (yes/no)"
If yes: add the free models to config with aliases

**Step 3: Default Model**
Ask: "Your current default model is [current model]. Want me to switch your default to MiniMax M2.5 ($0.04/request) or DeepSeek V3.2 ($0.04/request)? This alone saves 73-94% vs Opus/Sonnet. Options: minimax / deepseek / keep current"
If they choose: update model.primary

**Step 4: Heartbeat Optimization**
Ask: "Heartbeats keep your agent alive but cost money on expensive models. Want me to route heartbeats to a free model at 55-minute intervals? This saves $7-562/month depending on your current setup. Approve? (yes/no)"
If yes: set heartbeat model to free, interval 55m

**Step 5: Session Management**
Ask: "Want me to enable aggressive memory flush before compaction? This prevents context bloat and saves 10-30% on long sessions. Approve? (yes/no)"
If yes: enable memoryFlush with threshold 3000

**Step 6: Response Style**
Ask: "In cost-conscious mode, should I: (a) Always be concise to save tokens, (b) Be concise by default but go detailed when you ask, or (c) Keep my normal response style?"
Save preference to memory/cost-preferences.md

After setup, confirm: "Cost optimizer configured. Here's your estimated monthly cost: ~$X based on [usage estimate]. Use /cost-status anytime to check, /cost-setup to reconfigure."

---

## CHAPTER 1: MODEL TIERS AND ROUTING

When this skill is active and user hasn't overridden with [name], suggest the cheapest adequate model for each task.

### Understanding the Cost Structure

Every OpenClaw request sends approximately 140,000 tokens of fixed overhead (system prompt, tool schemas, context). This overhead is the dominant cost. What it costs depends entirely on which model processes it:

| Model Tier | Overhead Cost | Per Request | Monthly (50 q/day) |
|------------|--------------|-------------|-------------------|
| Free models | $0.00 | $0.00 | $0.00 |
| Budget (MiniMax/DeepSeek) | ~$0.04 | ~$0.04 | ~$60 |
| Mid (Haiku) | ~$0.14 | ~$0.15 | ~$225 |
| Quality (Sonnet) | ~$0.42 | ~$0.43 | ~$645 |
| Premium (Opus) | ~$0.70 | ~$0.71 | ~$1,065 |

A simple question costs $0.71 on Opus and $0.00 on a free model. The answer quality for simple factual questions is nearly identical. Model selection is the single biggest cost lever.

### Free Models (Tier 0 — $0.00/request)

These are your first choice for tasks that don't need premium quality:

| Alias | Model | Context | Good For |
|-------|-------|---------|----------|
| deepseek-free | DeepSeek V3 Free | 164K | Best free model overall. Coding, reasoning, general tasks. |
| llama-free | Llama 4 Scout Free | 512K | Largest context window. Research, long docs. |
| qwen-free | Qwen 3 235B Free | 40K | Multilingual and translation tasks. |
| mistral-free | Mistral Small 3.1 Free | 96K | Quick short answers. Classification. |
| gemma-free | Gemma 3 27B Free | 96K | Reliable fallback. |

If one free model is rate-limited, try the next: deepseek-free, llama-free, qwen-free, mistral-free, gemma-free

### Budget Models (Tier 1 — $0.01-0.14/request)

| Alias | Model | Cost/req | Good For |
|-------|-------|----------|----------|
| nano | GPT-5 Nano | ~$0.01 | Simplest tasks when free models are down |
| flashlite | Gemini Flash-Lite | ~$0.01 | Cron jobs, heartbeats |
| deepseek | DeepSeek V3.2 | ~$0.04 | Coding daily driver |
| minimax | MiniMax M2.5 | ~$0.04 | General daily driver (recommended default) |
| kimi | Kimi K2.5 | ~$0.07 | Long sessions — auto-caching drops to ~$0.02 after warmup |
| glm | GLM-5 | ~$0.14 | Complex architecture-level coding |

### Quality Models (Tier 2 — $0.15-0.53/request)

| Alias | Model | Cost/req | Good For |
|-------|-------|----------|----------|
| haiku | Claude Haiku 4.5 | ~$0.15 | Mid-tier quality work |
| sonnet | Claude Sonnet 4.6 | ~$0.53 | Quality writing, code review, final polish |

### Premium Models (Tier 3 — $0.71+/request)

| Alias | Model | Cost/req | Good For |
|-------|-------|----------|----------|
| opus | Claude Opus 4.6 | ~$0.71 | Maximum reasoning power |
| gpt5 | GPT-5 | ~$0.44 | Complex multi-domain tasks |

Use premium only when user explicitly requests or task genuinely requires it.

---

## CHAPTER 2: SMART ROUTING GUIDELINES

When this skill is active, use this decision process to suggest the best model for each task:

**Simple tasks — try free first:**
Factual questions, brainstorming, lists, first drafts, explanations, summaries, simple code, formatting, translations, yes/no questions, code scaffolds
Suggest: "I can handle this on [free model] at $0.00. Want me to proceed?"
If user hasn't set a preference yet, ask the first time. After that, follow their preference from setup.

**Standard work — use budget models:**
General questions needing reliable quality, coding tasks, analysis
Use the configured default (minimax or deepseek at ~$0.04)

**Long reasoning sessions:**
Multi-turn analysis, complex problem-solving
Suggest kimi ($0.07 first request, ~$0.02 after due to auto-caching)

**Complex coding:**
Systems architecture, difficult debugging
Suggest glm ($0.14) — only when task is genuinely complex

**Quality output for external sharing:**
Final versions of writing, thorough code reviews, research synthesis
Suggest doing research/gathering on budget model first, then switching to sonnet ($0.53) for the final output only.
Ask: "Draft complete. Want me to polish on Sonnet (~$0.53) or is this good enough?"

**Premium reasoning:**
Never auto-select opus. Instead ask: "This seems to need deep reasoning. Want me to use Opus (~$0.71/request) or try Sonnet first (~$0.53)?"

**User override:**
If user says /model [alias], use that model. No questions.
Resume smart routing after /reset or /model auto.

---

## CHAPTER 3: RESPONSE EFFICIENCY

When the user chose concise mode during setup, follow these guidelines to reduce output tokens:

### Response Length Guidelines

| Task Type | Target Length | Example |
|-----------|-------------|---------|
| Yes/No questions | 1-2 senten