{
  "schemaVersion": "1.0",
  "item": {
    "slug": "openclaw-token-optimizer",
    "name": "OpenClaw Token Optimizer",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/Asif2BD/openclaw-token-optimizer",
    "canonicalUrl": "https://clawhub.ai/Asif2BD/openclaw-token-optimizer",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/openclaw-token-optimizer",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openclaw-token-optimizer",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "README.md",
      "SECURITY.md",
      "CHANGELOG.md",
      ".clawhubsafe",
      "scripts/context_optimizer.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/openclaw-token-optimizer"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/openclaw-token-optimizer",
    "agentPageUrl": "https://openagent3.xyz/skills/openclaw-token-optimizer/agent",
    "manifestUrl": "https://openagent3.xyz/skills/openclaw-token-optimizer/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/openclaw-token-optimizer/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Token Optimizer",
        "body": "Comprehensive toolkit for reducing token usage and API costs in OpenClaw deployments. Combines smart model routing, optimized heartbeat intervals, usage tracking, and multi-provider strategies."
      },
      {
        "title": "Quick Start",
        "body": "Immediate actions (no config changes needed):\n\nGenerate optimized AGENTS.md (BIGGEST WIN!):\npython3 scripts/context_optimizer.py generate-agents\n# Creates AGENTS.md.optimized — review and replace your current AGENTS.md\n\n\n\nCheck what context you ACTUALLY need:\npython3 scripts/context_optimizer.py recommend \"hi, how are you?\"\n# Shows: Only 2 files needed (not 50+!)\n\n\n\nInstall optimized heartbeat:\ncp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md\n\n\n\nEnforce cheaper models for casual chat:\npython3 scripts/model_router.py \"thanks!\"\n# Single-provider Anthropic setup: Use Sonnet, not Opus\n# Multi-provider setup (OpenRouter/Together): Use Haiku for max savings\n\n\n\nCheck current token budget:\npython3 scripts/token_tracker.py check\n\nExpected savings: 50-80% reduction in token costs for typical workloads (context optimization is the biggest factor!)."
      },
      {
        "title": "0. Lazy Skill Loading (NEW in v3.0 — BIGGEST WIN!)",
        "body": "The single highest-impact optimization available. Most agents burn 3,000–15,000 tokens per session loading skill files they never use. Stop that first.\n\nThe pattern:\n\nCreate a lightweight SKILLS.md catalog in your workspace (~300 tokens — list of skills + when to load them)\nOnly load individual SKILL.md files when a task actually needs them\nApply the same logic to memory files — load MEMORY.md at startup, daily logs only on demand\n\nToken savings:\n\nLibrary sizeBefore (eager)After (lazy)Savings5 skills~3,000 tokens~600 tokens80%10 skills~6,500 tokens~750 tokens88%20 skills~13,000 tokens~900 tokens93%\n\nQuick implementation in AGENTS.md:\n\n## Skills\n\nAt session start: Read SKILLS.md (the index only — ~300 tokens).\nLoad individual skill files ONLY when a task requires them.\nNever load all skills upfront.\n\nFull implementation (with catalog template + optimizer script):\n\nclawhub install openclaw-skill-lazy-loader\n\nThe companion skill openclaw-skill-lazy-loader includes a SKILLS.md.template, an AGENTS.md.template lazy-loading section, and a context_optimizer.py CLI that recommends exactly which skills to load for any given task.\n\nLazy loading handles context loading costs. The remaining capabilities below handle runtime costs. Together they cover the full token lifecycle."
      },
      {
        "title": "1. Context Optimization (NEW!)",
        "body": "Biggest token saver — Only load files you actually need, not everything upfront.\n\nProblem: Default OpenClaw loads ALL context files every session:\n\nSOUL.md, AGENTS.md, USER.md, TOOLS.md, MEMORY.md\ndocs/**/*.md (hundreds of files)\nmemory/2026-*.md (daily logs)\nTotal: Often 50K+ tokens before user even speaks!\n\nSolution: Lazy loading based on prompt complexity.\n\nUsage:\n\npython3 scripts/context_optimizer.py recommend \"<user prompt>\"\n\nExamples:\n\n# Simple greeting → minimal context (2 files only!)\ncontext_optimizer.py recommend \"hi\"\n→ Load: SOUL.md, IDENTITY.md\n→ Skip: Everything else\n→ Savings: ~80% of context\n\n# Standard work → selective loading\ncontext_optimizer.py recommend \"write a function\"\n→ Load: SOUL.md, IDENTITY.md, memory/TODAY.md\n→ Skip: docs, old memory, knowledge base\n→ Savings: ~50% of context\n\n# Complex task → full context\ncontext_optimizer.py recommend \"analyze our entire architecture\"\n→ Load: SOUL.md, IDENTITY.md, MEMORY.md, memory/TODAY+YESTERDAY.md\n→ Conditionally load: Relevant docs only\n→ Savings: ~30% of context\n\nOutput format:\n\n{\n  \"complexity\": \"simple\",\n  \"context_level\": \"minimal\",\n  \"recommended_files\": [\"SOUL.md\", \"IDENTITY.md\"],\n  \"file_count\": 2,\n  \"savings_percent\": 80,\n  \"skip_patterns\": [\"docs/**/*.md\", \"memory/20*.md\"]\n}\n\nIntegration pattern:\nBefore loading context for a new session:\n\nfrom context_optimizer import recommend_context_bundle\n\nuser_prompt = \"thanks for your help\"\nrecommendation = recommend_context_bundle(user_prompt)\n\nif recommendation[\"context_level\"] == \"minimal\":\n    # Load only SOUL.md + IDENTITY.md\n    # Skip everything else\n    # Save ~80% tokens!\n\nGenerate optimized AGENTS.md:\n\ncontext_optimizer.py generate-agents\n# Creates AGENTS.md.optimized with lazy loading instructions\n# Review and replace your current AGENTS.md\n\nExpected savings: 50-80% reduction in context tokens."
      },
      {
        "title": "2. Smart Model Routing (ENHANCED!)",
        "body": "Automatically classify tasks and route to appropriate model tiers.\n\nNEW: Communication pattern enforcement — Never waste Opus tokens on \"hi\" or \"thanks\"!\n\nUsage:\n\npython3 scripts/model_router.py \"<user prompt>\" [current_model] [force_tier]\n\nExamples:\n\n# Communication (NEW!) → ALWAYS Haiku\npython3 scripts/model_router.py \"thanks!\"\npython3 scripts/model_router.py \"hi\"\npython3 scripts/model_router.py \"ok got it\"\n→ Enforced: Haiku (NEVER Sonnet/Opus for casual chat)\n\n# Simple task → suggests Haiku\npython3 scripts/model_router.py \"read the log file\"\n\n# Medium task → suggests Sonnet\npython3 scripts/model_router.py \"write a function to parse JSON\"\n\n# Complex task → suggests Opus\npython3 scripts/model_router.py \"design a microservices architecture\"\n\nPatterns enforced to Haiku (NEVER Sonnet/Opus):\n\nCommunication:\n\nGreetings: hi, hey, hello, yo\nThanks: thanks, thank you, thx\nAcknowledgments: ok, sure, got it, understood\nShort responses: yes, no, yep, nope\nSingle words or very short phrases\n\nBackground tasks:\n\nHeartbeat checks: \"check email\", \"monitor servers\"\nCronjobs: \"scheduled task\", \"periodic check\", \"reminder\"\nDocument parsing: \"parse CSV\", \"extract data from log\", \"read JSON\"\nLog scanning: \"scan error logs\", \"process logs\"\n\nIntegration pattern:\n\nfrom model_router import route_task\n\nuser_prompt = \"show me the config\"\nrouting = route_task(user_prompt)\n\nif routing[\"should_switch\"]:\n    # Use routing[\"recommended_model\"]\n    # Save routing[\"cost_savings_percent\"]\n\nCustomization:\nEdit ROUTING_RULES or COMMUNICATION_PATTERNS in scripts/model_router.py to adjust patterns and keywords."
      },
      {
        "title": "3. Heartbeat Optimization",
        "body": "Reduce API calls from heartbeat polling with smart interval tracking:\n\nSetup:\n\n# Copy template to workspace\ncp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md\n\n# Plan which checks should run\npython3 scripts/heartbeat_optimizer.py plan\n\nCommands:\n\n# Check if specific type should run now\nheartbeat_optimizer.py check email\nheartbeat_optimizer.py check calendar\n\n# Record that a check was performed\nheartbeat_optimizer.py record email\n\n# Update check interval (seconds)\nheartbeat_optimizer.py interval email 7200  # 2 hours\n\n# Reset state\nheartbeat_optimizer.py reset\n\nHow it works:\n\nTracks last check time for each type (email, calendar, weather, etc.)\nEnforces minimum intervals before re-checking\nRespects quiet hours (23:00-08:00) — skips all checks\nReturns HEARTBEAT_OK when nothing needs attention (saves tokens)\n\nDefault intervals:\n\nEmail: 60 minutes\nCalendar: 2 hours\nWeather: 4 hours\nSocial: 2 hours\nMonitoring: 30 minutes\n\nIntegration in HEARTBEAT.md:\n\n## Email Check\nRun only if: `heartbeat_optimizer.py check email` → `should_check: true`\nAfter checking: `heartbeat_optimizer.py record email`\n\nExpected savings: 50% reduction in heartbeat API calls.\n\nModel enforcement: Heartbeat should ALWAYS use Haiku — see updated HEARTBEAT.template.md for model override instructions."
      },
      {
        "title": "4. Cronjob Optimization (NEW!)",
        "body": "Problem: Cronjobs often default to expensive models (Sonnet/Opus) even for routine tasks.\n\nSolution: Always specify Haiku for 90% of scheduled tasks.\n\nSee: assets/cronjob-model-guide.md for comprehensive guide with examples.\n\nQuick reference:\n\nTask TypeModelExampleMonitoring/alertsHaikuCheck server health, disk spaceData parsingHaikuExtract CSV/JSON/logsRemindersHaikuDaily standup, backup remindersSimple reportsHaikuStatus summariesContent generationSonnetBlog summaries (quality matters)Deep analysisSonnetWeekly insightsComplex reasoningNever use Opus for cronjobs\n\nExample (good):\n\n# Parse daily logs with Haiku\ncron add --schedule \"0 2 * * *\" \\\n  --payload '{\n    \"kind\":\"agentTurn\",\n    \"message\":\"Parse yesterday error logs and summarize\",\n    \"model\":\"anthropic/claude-haiku-4\"\n  }' \\\n  --sessionTarget isolated\n\nExample (bad):\n\n# ❌ Using Opus for simple check (60x more expensive!)\ncron add --schedule \"*/15 * * * *\" \\\n  --payload '{\n    \"kind\":\"agentTurn\",\n    \"message\":\"Check email\",\n    \"model\":\"anthropic/claude-opus-4\"\n  }' \\\n  --sessionTarget isolated\n\nSavings: Using Haiku instead of Opus for 10 daily cronjobs = $17.70/month saved per agent.\n\nIntegration with model_router:\n\n# Test if your cronjob should use Haiku\nmodel_router.py \"parse daily error logs\"\n# → Output: Haiku (background task pattern detected)"
      },
      {
        "title": "5. Token Budget Tracking",
        "body": "Monitor usage and alert when approaching limits:\n\nSetup:\n\n# Check current daily usage\npython3 scripts/token_tracker.py check\n\n# Get model suggestions\npython3 scripts/token_tracker.py suggest general\n\n# Reset daily tracking\npython3 scripts/token_tracker.py reset\n\nOutput format:\n\n{\n  \"date\": \"2026-02-06\",\n  \"cost\": 2.50,\n  \"tokens\": 50000,\n  \"limit\": 5.00,\n  \"percent_used\": 50,\n  \"status\": \"ok\",\n  \"alert\": null\n}\n\nStatus levels:\n\nok: Below 80% of daily limit\nwarning: 80-99% of daily limit\nexceeded: Over daily limit\n\nIntegration pattern:\nBefore starting expensive operations, check budget:\n\nimport json\nimport subprocess\n\nresult = subprocess.run(\n    [\"python3\", \"scripts/token_tracker.py\", \"check\"],\n    capture_output=True, text=True\n)\nbudget = json.loads(result.stdout)\n\nif budget[\"status\"] == \"exceeded\":\n    # Switch to cheaper model or defer non-urgent work\n    use_model = \"anthropic/claude-haiku-4\"\nelif budget[\"status\"] == \"warning\":\n    # Use balanced model\n    use_model = \"anthropic/claude-sonnet-4-5\"\n\nCustomization:\nEdit daily_limit_usd and warn_threshold parameters in function calls."
      },
      {
        "title": "6. Multi-Provider Strategy",
        "body": "See references/PROVIDERS.md for comprehensive guide on:\n\nAlternative providers (OpenRouter, Together.ai, Google AI Studio)\nCost comparison tables\nRouting strategies by task complexity\nFallback chains for rate-limited scenarios\nAPI key management\n\nQuick reference:\n\nProviderModelCost/MTokUse CaseAnthropicHaiku 4$0.25Simple tasksAnthropicSonnet 4.5$3.00Balanced defaultAnthropicOpus 4$15.00Complex reasoningOpenRouterGemini 2.5 Flash$0.075Bulk operationsGoogle AIGemini 2.0 Flash ExpFREEDev/testingTogetherLlama 3.3 70B$0.18Open alternative"
      },
      {
        "title": "Configuration Patches",
        "body": "See assets/config-patches.json for advanced optimizations:\n\nImplemented by this skill:\n\n✅ Heartbeat optimization (fully functional)\n✅ Token budget tracking (fully functional)\n✅ Model routing logic (fully functional)\n\nNative OpenClaw 2026.2.15 — apply directly:\n\n✅ Session pruning (contextPruning: cache-ttl) — auto-trims old tool results after Anthropic cache TTL expires\n✅ Bootstrap size limits (bootstrapMaxChars / bootstrapTotalMaxChars) — caps workspace file injection size\n✅ Cache retention long (cacheRetention: \"long\" for Opus) — amortizes cache write costs\n\nRequires OpenClaw core support:\n\n⏳ Prompt caching (Anthropic API feature — verify current status)\n⏳ Lazy context loading (use context_optimizer.py script today)\n⏳ Multi-provider fallback (partially supported)\n\nApply config patches:\n\n# Example: Enable multi-provider fallback\ngateway config.patch --patch '{\"providers\": [...]}'"
      },
      {
        "title": "Native OpenClaw Diagnostics (2026.2.15+)",
        "body": "OpenClaw 2026.2.15 added built-in commands that complement this skill's Python scripts. Use these first for quick diagnostics before reaching for the scripts."
      },
      {
        "title": "Context breakdown",
        "body": "/context list    → token count per injected file (shows exactly what's eating your prompt)\n/context detail  → full breakdown including tools, skills, and system prompt sections\n\nUse before applying bootstrap_size_limits — see which files are oversized, then set bootstrapMaxChars accordingly."
      },
      {
        "title": "Per-response usage tracking",
        "body": "/usage tokens    → append token count to every reply\n/usage full      → append tokens + cost estimate to every reply\n/usage cost      → show cumulative cost summary from session logs\n/usage off       → disable usage footer\n\nCombine with token_tracker.py — /usage cost gives session totals; token_tracker.py tracks daily budget."
      },
      {
        "title": "Session status",
        "body": "/status          → model, context %, last response tokens, estimated cost"
      },
      {
        "title": "Cache TTL Heartbeat Alignment (NEW in v1.4.0)",
        "body": "The problem: Anthropic charges ~3.75x more for cache writes than cache reads. If your agent goes idle and the 1h cache TTL expires, the next request re-writes the entire prompt cache — expensive.\n\nThe fix: Set heartbeat interval to 55min (just under the 1h TTL). The heartbeat keeps the cache warm, so every subsequent request pays cache-read rates instead.\n\n# Get optimal interval for your cache TTL\npython3 scripts/heartbeat_optimizer.py cache-ttl\n# → recommended_interval: 55min (3300s)\n# → explanation: keeps 1h Anthropic cache warm\n\n# Custom TTL (e.g., if you've configured 2h cache)\npython3 scripts/heartbeat_optimizer.py cache-ttl 7200\n# → recommended_interval: 115min\n\nApply to your OpenClaw config:\n\n{\n  \"agents\": {\n    \"defaults\": {\n      \"heartbeat\": {\n        \"every\": \"55m\"\n      }\n    }\n  }\n}\n\nWho benefits: Anthropic API key users only. OAuth profiles already default to 1h heartbeat (OpenClaw smart default). API key profiles default to 30min — bumping to 55min is both cheaper (fewer calls) and cache-warm."
      },
      {
        "title": "For Personal Use",
        "body": "Install optimized HEARTBEAT.md\nRun budget checks before expensive operations\nManually route complex tasks to Opus only when needed\n\nExpected savings: 20-30%"
      },
      {
        "title": "For Managed Hosting (xCloud, etc.)",
        "body": "Default all agents to Haiku\nRoute user interactions to Sonnet\nReserve Opus for explicitly complex requests\nUse Gemini Flash for background operations\nImplement daily budget caps per customer\n\nExpected savings: 40-60%"
      },
      {
        "title": "For High-Volume Deployments",
        "body": "Use multi-provider fallback (OpenRouter + Together.ai)\nImplement aggressive routing (80% Gemini, 15% Haiku, 5% Sonnet)\nDeploy local Ollama for offline/cheap operations\nBatch heartbeat checks (every 2-4 hours, not 30 min)\n\nExpected savings: 70-90%"
      },
      {
        "title": "Workflow: Smart Task Handling",
        "body": "# 1. User sends message\nuser_msg=\"debug this error in the logs\"\n\n# 2. Route to appropriate model\nrouting=$(python3 scripts/model_router.py \"$user_msg\")\nmodel=$(echo $routing | jq -r .recommended_model)\n\n# 3. Check budget before proceeding\nbudget=$(python3 scripts/token_tracker.py check)\nstatus=$(echo $budget | jq -r .status)\n\nif [ \"$status\" = \"exceeded\" ]; then\n    # Use cheapest model regardless of routing\n    model=\"anthropic/claude-haiku-4\"\nfi\n\n# 4. Process with selected model\n# (OpenClaw handles this via config or override)"
      },
      {
        "title": "Workflow: Optimized Heartbeat",
        "body": "## HEARTBEAT.md\n\n# Plan what to check\nresult=$(python3 scripts/heartbeat_optimizer.py plan)\nshould_run=$(echo $result | jq -r .should_run)\n\nif [ \"$should_run\" = \"false\" ]; then\n    echo \"HEARTBEAT_OK\"\n    exit 0\nfi\n\n# Run only planned checks\nplanned=$(echo $result | jq -r '.planned[].type')\n\nfor check in $planned; do\n    case $check in\n        email) check_email ;;\n        calendar) check_calendar ;;\n    esac\n    python3 scripts/heartbeat_optimizer.py record $check\ndone"
      },
      {
        "title": "Troubleshooting",
        "body": "Issue: Scripts fail with \"module not found\"\n\nFix: Ensure Python 3.7+ is installed. Scripts use only stdlib.\n\nIssue: State files not persisting\n\nFix: Check that ~/.openclaw/workspace/memory/ directory exists and is writable.\n\nIssue: Budget tracking shows $0.00\n\nFix: token_tracker.py needs integration with OpenClaw's session_status tool. Currently tracks manually recorded usage.\n\nIssue: Routing suggests wrong model tier\n\nFix: Customize ROUTING_RULES in model_router.py for your specific patterns."
      },
      {
        "title": "Maintenance",
        "body": "Daily:\n\nCheck budget status: token_tracker.py check\n\nWeekly:\n\nReview routing accuracy (are suggestions correct?)\nAdjust heartbeat intervals based on activity\n\nMonthly:\n\nCompare costs before/after optimization\nReview and update PROVIDERS.md with new options"
      },
      {
        "title": "Cost Estimation",
        "body": "Example: 100K tokens/day workload\n\nWithout skill:\n\n50K context tokens + 50K conversation tokens = 100K total\nAll Sonnet: 100K × $3/MTok = $0.30/day = $9/month\n\nStrategyContextModelDaily CostMonthlySavingsBaseline (no optimization)50KSonnet$0.30$9.000%Context opt only10K (-80%)Sonnet$0.18$5.4040%Model routing only50KMixed$0.18$5.4040%Both (this skill)10KMixed$0.09$2.7070%Aggressive + Gemini10KGemini$0.03$0.9090%\n\nKey insight: Context optimization (50K → 10K tokens) saves MORE than model routing!\n\nxCloud hosting scenario (100 customers, 50K tokens/customer/day):\n\nBaseline (all Sonnet, full context): $450/month\nWith token-optimizer: $135/month\nSavings: $315/month per 100 customers (70%)"
      },
      {
        "title": "Scripts (4 total)",
        "body": "context_optimizer.py — Context loading optimization and lazy loading (NEW!)\nmodel_router.py — Task classification, model suggestions, and communication enforcement (ENHANCED!)\nheartbeat_optimizer.py — Interval management and check scheduling\ntoken_tracker.py — Budget monitoring and alerts"
      },
      {
        "title": "References",
        "body": "PROVIDERS.md — Alternative AI providers, pricing, and routing strategies"
      },
      {
        "title": "Assets (3 total)",
        "body": "HEARTBEAT.template.md — Drop-in optimized heartbeat template with Haiku enforcement (ENHANCED!)\ncronjob-model-guide.md — Complete guide for choosing models in cronjobs (NEW!)\nconfig-patches.json — Advanced configuration examples"
      },
      {
        "title": "Future Enhancements",
        "body": "Ideas for extending this skill:\n\nAuto-routing integration — Hook into OpenClaw message pipeline\nReal-time usage tracking — Parse session_status automatically\nCost forecasting — Predict monthly spend based on recent usage\nProvider health monitoring — Track API latency and failures\nA/B testing — Compare quality across different routing strategies"
      }
    ],
    "body": "Token Optimizer\n\nComprehensive toolkit for reducing token usage and API costs in OpenClaw deployments. Combines smart model routing, optimized heartbeat intervals, usage tracking, and multi-provider strategies.\n\nQuick Start\n\nImmediate actions (no config changes needed):\n\nGenerate optimized AGENTS.md (BIGGEST WIN!):\n\npython3 scripts/context_optimizer.py generate-agents\n# Creates AGENTS.md.optimized — review and replace your current AGENTS.md\n\n\nCheck what context you ACTUALLY need:\n\npython3 scripts/context_optimizer.py recommend \"hi, how are you?\"\n# Shows: Only 2 files needed (not 50+!)\n\n\nInstall optimized heartbeat:\n\ncp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md\n\n\nEnforce cheaper models for casual chat:\n\npython3 scripts/model_router.py \"thanks!\"\n# Single-provider Anthropic setup: Use Sonnet, not Opus\n# Multi-provider setup (OpenRouter/Together): Use Haiku for max savings\n\n\nCheck current token budget:\n\npython3 scripts/token_tracker.py check\n\n\nExpected savings: 50-80% reduction in token costs for typical workloads (context optimization is the biggest factor!).\n\nCore Capabilities\n0. Lazy Skill Loading (NEW in v3.0 — BIGGEST WIN!)\n\nThe single highest-impact optimization available. Most agents burn 3,000–15,000 tokens per session loading skill files they never use. Stop that first.\n\nThe pattern:\n\nCreate a lightweight SKILLS.md catalog in your workspace (~300 tokens — list of skills + when to load them)\nOnly load individual SKILL.md files when a task actually needs them\nApply the same logic to memory files — load MEMORY.md at startup, daily logs only on demand\n\nToken savings:\n\nLibrary size\tBefore (eager)\tAfter (lazy)\tSavings\n5 skills\t~3,000 tokens\t~600 tokens\t80%\n10 skills\t~6,500 tokens\t~750 tokens\t88%\n20 skills\t~13,000 tokens\t~900 tokens\t93%\n\nQuick implementation in AGENTS.md:\n\n## Skills\n\nAt session start: Read SKILLS.md (the index only — ~300 tokens).\nLoad individual skill files ONLY when a task requires them.\nNever load all skills upfront.\n\n\nFull implementation (with catalog template + optimizer script):\n\nclawhub install openclaw-skill-lazy-loader\n\n\nThe companion skill openclaw-skill-lazy-loader includes a SKILLS.md.template, an AGENTS.md.template lazy-loading section, and a context_optimizer.py CLI that recommends exactly which skills to load for any given task.\n\nLazy loading handles context loading costs. The remaining capabilities below handle runtime costs. Together they cover the full token lifecycle.\n\n1. Context Optimization (NEW!)\n\nBiggest token saver — Only load files you actually need, not everything upfront.\n\nProblem: Default OpenClaw loads ALL context files every session:\n\nSOUL.md, AGENTS.md, USER.md, TOOLS.md, MEMORY.md\ndocs/**/*.md (hundreds of files)\nmemory/2026-*.md (daily logs)\nTotal: Often 50K+ tokens before user even speaks!\n\nSolution: Lazy loading based on prompt complexity.\n\nUsage:\n\npython3 scripts/context_optimizer.py recommend \"<user prompt>\"\n\n\nExamples:\n\n# Simple greeting → minimal context (2 files only!)\ncontext_optimizer.py recommend \"hi\"\n→ Load: SOUL.md, IDENTITY.md\n→ Skip: Everything else\n→ Savings: ~80% of context\n\n# Standard work → selective loading\ncontext_optimizer.py recommend \"write a function\"\n→ Load: SOUL.md, IDENTITY.md, memory/TODAY.md\n→ Skip: docs, old memory, knowledge base\n→ Savings: ~50% of context\n\n# Complex task → full context\ncontext_optimizer.py recommend \"analyze our entire architecture\"\n→ Load: SOUL.md, IDENTITY.md, MEMORY.md, memory/TODAY+YESTERDAY.md\n→ Conditionally load: Relevant docs only\n→ Savings: ~30% of context\n\n\nOutput format:\n\n{\n  \"complexity\": \"simple\",\n  \"context_level\": \"minimal\",\n  \"recommended_files\": [\"SOUL.md\", \"IDENTITY.md\"],\n  \"file_count\": 2,\n  \"savings_percent\": 80,\n  \"skip_patterns\": [\"docs/**/*.md\", \"memory/20*.md\"]\n}\n\n\nIntegration pattern: Before loading context for a new session:\n\nfrom context_optimizer import recommend_context_bundle\n\nuser_prompt = \"thanks for your help\"\nrecommendation = recommend_context_bundle(user_prompt)\n\nif recommendation[\"context_level\"] == \"minimal\":\n    # Load only SOUL.md + IDENTITY.md\n    # Skip everything else\n    # Save ~80% tokens!\n\n\nGenerate optimized AGENTS.md:\n\ncontext_optimizer.py generate-agents\n# Creates AGENTS.md.optimized with lazy loading instructions\n# Review and replace your current AGENTS.md\n\n\nExpected savings: 50-80% reduction in context tokens.\n\n2. Smart Model Routing (ENHANCED!)\n\nAutomatically classify tasks and route to appropriate model tiers.\n\nNEW: Communication pattern enforcement — Never waste Opus tokens on \"hi\" or \"thanks\"!\n\nUsage:\n\npython3 scripts/model_router.py \"<user prompt>\" [current_model] [force_tier]\n\n\nExamples:\n\n# Communication (NEW!) → ALWAYS Haiku\npython3 scripts/model_router.py \"thanks!\"\npython3 scripts/model_router.py \"hi\"\npython3 scripts/model_router.py \"ok got it\"\n→ Enforced: Haiku (NEVER Sonnet/Opus for casual chat)\n\n# Simple task → suggests Haiku\npython3 scripts/model_router.py \"read the log file\"\n\n# Medium task → suggests Sonnet\npython3 scripts/model_router.py \"write a function to parse JSON\"\n\n# Complex task → suggests Opus\npython3 scripts/model_router.py \"design a microservices architecture\"\n\n\nPatterns enforced to Haiku (NEVER Sonnet/Opus):\n\nCommunication:\n\nGreetings: hi, hey, hello, yo\nThanks: thanks, thank you, thx\nAcknowledgments: ok, sure, got it, understood\nShort responses: yes, no, yep, nope\nSingle words or very short phrases\n\nBackground tasks:\n\nHeartbeat checks: \"check email\", \"monitor servers\"\nCronjobs: \"scheduled task\", \"periodic check\", \"reminder\"\nDocument parsing: \"parse CSV\", \"extract data from log\", \"read JSON\"\nLog scanning: \"scan error logs\", \"process logs\"\n\nIntegration pattern:\n\nfrom model_router import route_task\n\nuser_prompt = \"show me the config\"\nrouting = route_task(user_prompt)\n\nif routing[\"should_switch\"]:\n    # Use routing[\"recommended_model\"]\n    # Save routing[\"cost_savings_percent\"]\n\n\nCustomization: Edit ROUTING_RULES or COMMUNICATION_PATTERNS in scripts/model_router.py to adjust patterns and keywords.\n\n3. Heartbeat Optimization\n\nReduce API calls from heartbeat polling with smart interval tracking:\n\nSetup:\n\n# Copy template to workspace\ncp assets/HEARTBEAT.template.md ~/.openclaw/workspace/HEARTBEAT.md\n\n# Plan which checks should run\npython3 scripts/heartbeat_optimizer.py plan\n\n\nCommands:\n\n# Check if specific type should run now\nheartbeat_optimizer.py check email\nheartbeat_optimizer.py check calendar\n\n# Record that a check was performed\nheartbeat_optimizer.py record email\n\n# Update check interval (seconds)\nheartbeat_optimizer.py interval email 7200  # 2 hours\n\n# Reset state\nheartbeat_optimizer.py reset\n\n\nHow it works:\n\nTracks last check time for each type (email, calendar, weather, etc.)\nEnforces minimum intervals before re-checking\nRespects quiet hours (23:00-08:00) — skips all checks\nReturns HEARTBEAT_OK when nothing needs attention (saves tokens)\n\nDefault intervals:\n\nEmail: 60 minutes\nCalendar: 2 hours\nWeather: 4 hours\nSocial: 2 hours\nMonitoring: 30 minutes\n\nIntegration in HEARTBEAT.md:\n\n## Email Check\nRun only if: `heartbeat_optimizer.py check email` → `should_check: true`\nAfter checking: `heartbeat_optimizer.py record email`\n\n\nExpected savings: 50% reduction in heartbeat API calls.\n\nModel enforcement: Heartbeat should ALWAYS use Haiku — see updated HEARTBEAT.template.md for model override instructions.\n\n4. Cronjob Optimization (NEW!)\n\nProblem: Cronjobs often default to expensive models (Sonnet/Opus) even for routine tasks.\n\nSolution: Always specify Haiku for 90% of scheduled tasks.\n\nSee: assets/cronjob-model-guide.md for comprehensive guide with examples.\n\nQuick reference:\n\nTask Type\tModel\tExample\nMonitoring/alerts\tHaiku\tCheck server health, disk space\nData parsing\tHaiku\tExtract CSV/JSON/logs\nReminders\tHaiku\tDaily standup, backup reminders\nSimple reports\tHaiku\tStatus summaries\nContent generation\tSonnet\tBlog summaries (quality matters)\nDeep analysis\tSonnet\tWeekly insights\nComplex reasoning\tNever use Opus for cronjobs\t\n\nExample (good):\n\n# Parse daily logs with Haiku\ncron add --schedule \"0 2 * * *\" \\\n  --payload '{\n    \"kind\":\"agentTurn\",\n    \"message\":\"Parse yesterday error logs and summarize\",\n    \"model\":\"anthropic/claude-haiku-4\"\n  }' \\\n  --sessionTarget isolated\n\n\nExample (bad):\n\n# ❌ Using Opus for simple check (60x more expensive!)\ncron add --schedule \"*/15 * * * *\" \\\n  --payload '{\n    \"kind\":\"agentTurn\",\n    \"message\":\"Check email\",\n    \"model\":\"anthropic/claude-opus-4\"\n  }' \\\n  --sessionTarget isolated\n\n\nSavings: Using Haiku instead of Opus for 10 daily cronjobs = $17.70/month saved per agent.\n\nIntegration with model_router:\n\n# Test if your cronjob should use Haiku\nmodel_router.py \"parse daily error logs\"\n# → Output: Haiku (background task pattern detected)\n\n5. Token Budget Tracking\n\nMonitor usage and alert when approaching limits:\n\nSetup:\n\n# Check current daily usage\npython3 scripts/token_tracker.py check\n\n# Get model suggestions\npython3 scripts/token_tracker.py suggest general\n\n# Reset daily tracking\npython3 scripts/token_tracker.py reset\n\n\nOutput format:\n\n{\n  \"date\": \"2026-02-06\",\n  \"cost\": 2.50,\n  \"tokens\": 50000,\n  \"limit\": 5.00,\n  \"percent_used\": 50,\n  \"status\": \"ok\",\n  \"alert\": null\n}\n\n\nStatus levels:\n\nok: Below 80% of daily limit\nwarning: 80-99% of daily limit\nexceeded: Over daily limit\n\nIntegration pattern: Before starting expensive operations, check budget:\n\nimport json\nimport subprocess\n\nresult = subprocess.run(\n    [\"python3\", \"scripts/token_tracker.py\", \"check\"],\n    capture_output=True, text=True\n)\nbudget = json.loads(result.stdout)\n\nif budget[\"status\"] == \"exceeded\":\n    # Switch to cheaper model or defer non-urgent work\n    use_model = \"anthropic/claude-haiku-4\"\nelif budget[\"status\"] == \"warning\":\n    # Use balanced model\n    use_model = \"anthropic/claude-sonnet-4-5\"\n\n\nCustomization: Edit daily_limit_usd and warn_threshold parameters in function calls.\n\n6. Multi-Provider Strategy\n\nSee references/PROVIDERS.md for comprehensive guide on:\n\nAlternative providers (OpenRouter, Together.ai, Google AI Studio)\nCost comparison tables\nRouting strategies by task complexity\nFallback chains for rate-limited scenarios\nAPI key management\n\nQuick reference:\n\nProvider\tModel\tCost/MTok\tUse Case\nAnthropic\tHaiku 4\t$0.25\tSimple tasks\nAnthropic\tSonnet 4.5\t$3.00\tBalanced default\nAnthropic\tOpus 4\t$15.00\tComplex reasoning\nOpenRouter\tGemini 2.5 Flash\t$0.075\tBulk operations\nGoogle AI\tGemini 2.0 Flash Exp\tFREE\tDev/testing\nTogether\tLlama 3.3 70B\t$0.18\tOpen alternative\nConfiguration Patches\n\nSee assets/config-patches.json for advanced optimizations:\n\nImplemented by this skill:\n\n✅ Heartbeat optimization (fully functional)\n✅ Token budget tracking (fully functional)\n✅ Model routing logic (fully functional)\n\nNative OpenClaw 2026.2.15 — apply directly:\n\n✅ Session pruning (contextPruning: cache-ttl) — auto-trims old tool results after Anthropic cache TTL expires\n✅ Bootstrap size limits (bootstrapMaxChars / bootstrapTotalMaxChars) — caps workspace file injection size\n✅ Cache retention long (cacheRetention: \"long\" for Opus) — amortizes cache write costs\n\nRequires OpenClaw core support:\n\n⏳ Prompt caching (Anthropic API feature — verify current status)\n⏳ Lazy context loading (use context_optimizer.py script today)\n⏳ Multi-provider fallback (partially supported)\n\nApply config patches:\n\n# Example: Enable multi-provider fallback\ngateway config.patch --patch '{\"providers\": [...]}'\n\nNative OpenClaw Diagnostics (2026.2.15+)\n\nOpenClaw 2026.2.15 added built-in commands that complement this skill's Python scripts. Use these first for quick diagnostics before reaching for the scripts.\n\nContext breakdown\n/context list    → token count per injected file (shows exactly what's eating your prompt)\n/context detail  → full breakdown including tools, skills, and system prompt sections\n\n\nUse before applying bootstrap_size_limits — see which files are oversized, then set bootstrapMaxChars accordingly.\n\nPer-response usage tracking\n/usage tokens    → append token count to every reply\n/usage full      → append tokens + cost estimate to every reply\n/usage cost      → show cumulative cost summary from session logs\n/usage off       → disable usage footer\n\n\nCombine with token_tracker.py — /usage cost gives session totals; token_tracker.py tracks daily budget.\n\nSession status\n/status          → model, context %, last response tokens, estimated cost\n\nCache TTL Heartbeat Alignment (NEW in v1.4.0)\n\nThe problem: Anthropic charges ~3.75x more for cache writes than cache reads. If your agent goes idle and the 1h cache TTL expires, the next request re-writes the entire prompt cache — expensive.\n\nThe fix: Set heartbeat interval to 55min (just under the 1h TTL). The heartbeat keeps the cache warm, so every subsequent request pays cache-read rates instead.\n\n# Get optimal interval for your cache TTL\npython3 scripts/heartbeat_optimizer.py cache-ttl\n# → recommended_interval: 55min (3300s)\n# → explanation: keeps 1h Anthropic cache warm\n\n# Custom TTL (e.g., if you've configured 2h cache)\npython3 scripts/heartbeat_optimizer.py cache-ttl 7200\n# → recommended_interval: 115min\n\n\nApply to your OpenClaw config:\n\n{\n  \"agents\": {\n    \"defaults\": {\n      \"heartbeat\": {\n        \"every\": \"55m\"\n      }\n    }\n  }\n}\n\n\nWho benefits: Anthropic API key users only. OAuth profiles already default to 1h heartbeat (OpenClaw smart default). API key profiles default to 30min — bumping to 55min is both cheaper (fewer calls) and cache-warm.\n\nDeployment Patterns\nFor Personal Use\nInstall optimized HEARTBEAT.md\nRun budget checks before expensive operations\nManually route complex tasks to Opus only when needed\n\nExpected savings: 20-30%\n\nFor Managed Hosting (xCloud, etc.)\nDefault all agents to Haiku\nRoute user interactions to Sonnet\nReserve Opus for explicitly complex requests\nUse Gemini Flash for background operations\nImplement daily budget caps per customer\n\nExpected savings: 40-60%\n\nFor High-Volume Deployments\nUse multi-provider fallback (OpenRouter + Together.ai)\nImplement aggressive routing (80% Gemini, 15% Haiku, 5% Sonnet)\nDeploy local Ollama for offline/cheap operations\nBatch heartbeat checks (every 2-4 hours, not 30 min)\n\nExpected savings: 70-90%\n\nIntegration Examples\nWorkflow: Smart Task Handling\n# 1. User sends message\nuser_msg=\"debug this error in the logs\"\n\n# 2. Route to appropriate model\nrouting=$(python3 scripts/model_router.py \"$user_msg\")\nmodel=$(echo $routing | jq -r .recommended_model)\n\n# 3. Check budget before proceeding\nbudget=$(python3 scripts/token_tracker.py check)\nstatus=$(echo $budget | jq -r .status)\n\nif [ \"$status\" = \"exceeded\" ]; then\n    # Use cheapest model regardless of routing\n    model=\"anthropic/claude-haiku-4\"\nfi\n\n# 4. Process with selected model\n# (OpenClaw handles this via config or override)\n\nWorkflow: Optimized Heartbeat\n## HEARTBEAT.md\n\n# Plan what to check\nresult=$(python3 scripts/heartbeat_optimizer.py plan)\nshould_run=$(echo $result | jq -r .should_run)\n\nif [ \"$should_run\" = \"false\" ]; then\n    echo \"HEARTBEAT_OK\"\n    exit 0\nfi\n\n# Run only planned checks\nplanned=$(echo $result | jq -r '.planned[].type')\n\nfor check in $planned; do\n    case $check in\n        email) check_email ;;\n        calendar) check_calendar ;;\n    esac\n    python3 scripts/heartbeat_optimizer.py record $check\ndone\n\nTroubleshooting\n\nIssue: Scripts fail with \"module not found\"\n\nFix: Ensure Python 3.7+ is installed. Scripts use only stdlib.\n\nIssue: State files not persisting\n\nFix: Check that ~/.openclaw/workspace/memory/ directory exists and is writable.\n\nIssue: Budget tracking shows $0.00\n\nFix: token_tracker.py needs integration with OpenClaw's session_status tool. Currently tracks manually recorded usage.\n\nIssue: Routing suggests wrong model tier\n\nFix: Customize ROUTING_RULES in model_router.py for your specific patterns.\nMaintenance\n\nDaily:\n\nCheck budget status: token_tracker.py check\n\nWeekly:\n\nReview routing accuracy (are suggestions correct?)\nAdjust heartbeat intervals based on activity\n\nMonthly:\n\nCompare costs before/after optimization\nReview and update PROVIDERS.md with new options\nCost Estimation\n\nExample: 100K tokens/day workload\n\nWithout skill:\n\n50K context tokens + 50K conversation tokens = 100K total\nAll Sonnet: 100K × $3/MTok = $0.30/day = $9/month\nStrategy\tContext\tModel\tDaily Cost\tMonthly\tSavings\nBaseline (no optimization)\t50K\tSonnet\t$0.30\t$9.00\t0%\nContext opt only\t10K (-80%)\tSonnet\t$0.18\t$5.40\t40%\nModel routing only\t50K\tMixed\t$0.18\t$5.40\t40%\nBoth (this skill)\t10K\tMixed\t$0.09\t$2.70\t70%\nAggressive + Gemini\t10K\tGemini\t$0.03\t$0.90\t90%\n\nKey insight: Context optimization (50K → 10K tokens) saves MORE than model routing!\n\nxCloud hosting scenario (100 customers, 50K tokens/customer/day):\n\nBaseline (all Sonnet, full context): $450/month\nWith token-optimizer: $135/month\nSavings: $315/month per 100 customers (70%)\nResources\nScripts (4 total)\ncontext_optimizer.py — Context loading optimization and lazy loading (NEW!)\nmodel_router.py — Task classification, model suggestions, and communication enforcement (ENHANCED!)\nheartbeat_optimizer.py — Interval management and check scheduling\ntoken_tracker.py — Budget monitoring and alerts\nReferences\nPROVIDERS.md — Alternative AI providers, pricing, and routing strategies\nAssets (3 total)\nHEARTBEAT.template.md — Drop-in optimized heartbeat template with Haiku enforcement (ENHANCED!)\ncronjob-model-guide.md — Complete guide for choosing models in cronjobs (NEW!)\nconfig-patches.json — Advanced configuration examples\nFuture Enhancements\n\nIdeas for extending this skill:\n\nAuto-routing integration — Hook into OpenClaw message pipeline\nReal-time usage tracking — Parse session_status automatically\nCost forecasting — Predict monthly spend based on recent usage\nProvider health monitoring — Track API latency and failures\nA/B testing — Compare quality across different routing strategies"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/Asif2BD/openclaw-token-optimizer",
    "publisherUrl": "https://clawhub.ai/Asif2BD/openclaw-token-optimizer",
    "owner": "Asif2BD",
    "version": "3.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/openclaw-token-optimizer",
    "downloadUrl": "https://openagent3.xyz/downloads/openclaw-token-optimizer",
    "agentUrl": "https://openagent3.xyz/skills/openclaw-token-optimizer/agent",
    "manifestUrl": "https://openagent3.xyz/skills/openclaw-token-optimizer/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/openclaw-token-optimizer/agent.md"
  }
}