proxy-token-optimizer

Optimize LLM token usage and API costs for the openclaw-manager proxy platform. Provides model-tier routing (route simple prompts to glm-4.7-flashx instead o...

Security Scan

The skill generally matches its stated purpose (token/model routing and cost reports) but has concerning gaps: it is force-enabled (always: true) while containing platform-side DB access code that isn't declared in requirements, which increases the risk of unexpected data access.

Purpose & Capability

The name/description align with the included scripts: model routing, context lazy-loading, heartbeat patch generation, and PostgreSQL-backed usage reports. However, the skill includes platform-side code that expects an openclaw-manager runtime (DB/session/settings) but the skill declares no required environment variables or config paths to indicate that database credentials or project context are needed.

Instruction Scope

SKILL.md and the scripts instruct the agent/operator to query the usage_records PostgreSQL table and import app.database/app.settings when running platform-side reports. The README also directs automatic use 'whenever the user mentions token optimization', which combined with always: true grants broad discretionary invocation. The instructions do not explicitly require user confirmation before running DB queries or clarify which commands require elevated access.

Install Mechanism

There is no install spec (instruction-only install), so nothing is fetched from external URLs or installed automatically. All code ships inside the skill bundle; this is low-install risk.

Credentials

Platform-side scripts need access to the project's DB/session and settings (they import app.database and app.settings), which implies database credentials/config are required. The skill declares no required env vars or config paths (primaryEnv is none). This is a mismatch: the skill will only work if run within the openclaw-manager environment, and the lack of explicit credential/config requirements obscures the fact that it may access sensitive DB records.

Persistence & Privilege

The skill metadata sets always: true (force-included in every agent run). That is a significant privilege here because the skill contains code capable of querying local project databases. Always-enabled combined with potential autonomous invocation increases the blast radius; the SKILL.md's broad trigger rules strengthen the concern because the skill could be invoked in many contexts without explicit user intent.

What to consider before installing

This skill appears to do what it claims (routing, context optimization, heartbeat config, and DB-backed usage reports) but there are red flags you should address before enabling it widely: - always: true is set. That forces this skill into every agent run. Remove or justify always: true unless you need the skill globally; prefer explicit invocation. - The platform-side scripts import app.database and app.settings and will query PostgreSQL. That requires running inside the openclaw-manager environment with DB credentials present — but the skill does not declare these credentials or config paths. Treat DB access as sensitive: require explicit user consent before running those commands and restrict where the skill can run. - If you plan to use the usage_report/quota_advisor features, run them manually from the openclaw-manager project root in a controlled environment first. Inspect the queries and ensure they only read required tables/columns and that the DB user has least privilege. - Because the skill writes files (AGENTS.md.optimized and other patches), review generated output before applying it to production configs. - If you enable autonomous invocation, restrict the skill's triggers or remove always: true; otherwise the agent may call into code that touches your DB without explicit operator confirmation. Bottom line: the code is coherent with the stated purpose, but the combination of always: true + undeclared DB access is disproportionate and worth fixing before installation.

Reduces LLM API costs for the openclaw-manager multi-tenant proxy platform through four strategies:

1. Model-tier routing — Route prompts to the cheapest capable model
2. Heartbeat optimization — Cheapest model + longer intervals for heartbeat calls
3. Context lazy loading — Load only the context files each prompt actually needs
4. Platform usage analytics — Real data from PostgreSQL, not estimates

Why these strategies matter

The openclaw-manager platform proxies LLM requests for multiple OpenClaw instances through providers like zai-proxy, zai-coding-proxy, and kimi-coding-proxy. Each provider offers models at different price points (e.g., glm-4.7 vs glm-4.7-flashx). Without optimization, every request — including simple greetings and heartbeat pings — uses the default (expensive) model, and every session loads the full context regardless of need. These four strategies target the highest-impact cost drivers.

Quick start

All instance-side scripts run locally with no dependencies. Platform-side scripts need DB access.

# Model routing — which model should handle this prompt?
python3 scripts/model_router.py "thanks!"
# → {"tier": "cheap", "recommended_model": "zai-proxy/glm-4.7-flashx"}

# Context optimization — which files does this prompt need?
python3 scripts/context_optimizer.py recommend "hi"
# → {"context_level": "minimal", "recommended_files": ["SOUL.md", "IDENTITY.md"]}

# Heartbeat config — generate openclaw.json patch
python3 scripts/heartbeat_config.py patch
# → {"agents": {"defaults": {"heartbeat": {"every": "55m", "model": "zai-proxy/glm-4.7-flashx"}}}}

# Unified CLI (all commands in one place)
python3 scripts/cli.py --help

Scripts reference

Instance-side (pure local, no network, no DB)

scripts/model_router.py

Routes prompts to the right model tier based on complexity analysis.

Tier logic:

• cheap → glm-4.7-flashx: Greetings, acknowledgments, heartbeats, cron jobs, log parsing. Cost savings: 5-10x vs standard.
• standard → glm-4.7: Code writing, debugging, explanations. Default for unclear prompts.
• premium → glm-4.7 (or k2p5 for kimi): Architecture design, deep analysis, strategy planning.

Supports Chinese and English patterns. Provider-aware — works with zai-proxy, zai-coding-proxy, and kimi-coding-proxy.

python3 scripts/model_router.py "<prompt>" [provider]
python3 scripts/model_router.py compare  # show all provider models

scripts/context_optimizer.py

Analyzes prompt complexity to recommend which context files to load, reducing unnecessary token consumption.

Context levels:

Level	When	Files loaded	Token savings
minimal	"hi", "thanks", short msgs	SOUL.md + IDENTITY.md (2)	~80%
standard	"write a function", normal work	+ memory/TODAY.md + conditional	~50%
full	"design architecture", complex tasks	+ MEMORY.md + all conditional	~30%

Also generates an optimized AGENTS.md template with lazy-loading rules baked in:

python3 scripts/context_optimizer.py recommend "<prompt>"
python3 scripts/context_optimizer.py generate-agents  # creates AGENTS.md.optimized

scripts/heartbeat_config.py

Generates openclaw.json configuration patches for heartbeat optimization:

• Forces heartbeat model to glm-4.7-flashx (cheapest available)
• Sets interval to 55 minutes (keeps prompt cache warm within 1-hour TTL, avoids cache rebuild cost)

python3 scripts/heartbeat_config.py recommend [cache_ttl_minutes]
python3 scripts/heartbeat_config.py patch  # output JSON patch for openclaw.json

Platform-side (requires DB connection)

These scripts query the usage_records PostgreSQL table for real data. Run from the openclaw-manager project root with the virtualenv activated.

scripts/usage_report.py

Generates usage reports from actual database records — not estimates.

python3 scripts/usage_report.py overview [days]     # platform-wide summary
python3 scripts/usage_report.py instance <name> [days]  # single instance detail

Overview includes: total calls/tokens, per-provider breakdown, per-model breakdown, top 10 instances by consumption, 7-day daily trend.

Instance report includes: per-model distribution, daily trend, lifetime totals.

scripts/quota_advisor.py

Compares actual 24-hour usage against quota plan limits to find mismatches:

• Wasteful: Usage below 20% of plan limit → suggest downgrade
• Throttled: Usage above 80% of plan limit → suggest upgrade

python3 scripts/quota_advisor.py analyze  # check all instances
python3 scripts/quota_advisor.py plans    # show available quota plans

Unified CLI

scripts/cli.py wraps all the above into a single entry point:

python3 scripts/cli.py route "<prompt>"       # model routing
python3 scripts/cli.py context "<prompt>"     # context recommendation
python3 scripts/cli.py generate-agents        # generate AGENTS.md
python3 scripts/cli.py heartbeat              # heartbeat config
python3 scripts/cli.py overview [days]        # platform usage (needs DB)
python3 scripts/cli.py report <name> [days]   # instance report (needs DB)
python3 scripts/cli.py advisor                # quota advice (needs DB)

Project integration points

This skill works with existing openclaw-manager infrastructure:

Component	File	How this skill uses it
Provider config	config/model.yaml	Model names/endpoints for routing
Proxy routing	config_service.py	Where _inject_proxy_providers() registers models
Usage recording	proxy_common/usage_recorder.py	Source of real usage data
Quota plans	config/llm_proxy.yaml	Plan definitions for quota advisor
Instance model	app/models.py	Instance metadata for reports

Expected savings

Strategy	Mechanism	Impact
Context lazy loading	Fewer tokens per request	50-80% context reduction
Model routing (flashx)	Lower per-token price	5-10x on simple tasks
Heartbeat → flashx	Lower heartbeat cost	Significant per-instance savings
Heartbeat interval 55min	Fewer API calls	~45% fewer heartbeat calls