router-rule-tuner

name	router-rule-tuner
description	Analyze OpenClaw Router decision logs, compare routing patterns against actual usage, and tune OpenClaw Router thresholds, weights, keywords, and fallback candidates for OpenClaw. Use when the goal is to reduce API token usage without materially reducing quality, especially in a local-first routing setup.

Router Rule Tuner

Use this skill when OpenClaw Router needs to be tuned from real decision logs.

Primary objective:

• keep quality acceptable,
• reduce paid/API model usage,
• keep simple and low-risk requests on local models whenever possible,
• escalate to API models only when the prompt likely needs stronger capability.

This skill runs in observation mode by default:

• do not rewrite config automatically,
• do not rewrite plugin logic automatically,
• produce analysis and recommendations first,
• estimate API usage reduction with local models treated as zero-cost.

Inputs

• Decision log JSONL: ~/.openclaw/logs/router-decisions.jsonl unless the user configured another path.
• Current OpenClaw Router config: plugins.entries.router.config in ~/.openclaw/openclaw.json.
• Optional runtime evidence: ~/.openclaw/logs/gateway.log for fallback failures or provider errors.

Workflow

1. Read the current OpenClaw Router config and confirm the decision log path.
2. Run scripts/analyze_router_logs.mjs against the JSONL log.
3. Use the summary to find skew and borderline routing:
   • tierDistribution: catches over-routing into one tier.
   • borderlineCounts: shows prompts close to threshold boundaries.
   • fallbackUsage: shows which fallback candidates are most often planned.
   • topSignals: shows which features are actually driving decisions.
   • usageMix: shows how many requests stayed local vs used API-backed models.
4. Read recommendations from the analyzer output.
5. If needed, inspect recent gateway logs around the same timestamps to see whether chosen models failed or fell back.
6. Make conservative adjustments:
   • Change one threshold or one small group of related weights at a time.
   • Keep changes within about 0.2 to 0.5 for weights and 50 to 150 chars for length thresholds unless the log is clearly skewed.
   • Prefer changing thresholds before adding more keywords.
   • Prefer changing keywords before changing fallback pools.
   • Prefer changes that move borderline cost-optimized-solving traffic to efficient-response local routing.
   • Do not recommend changes that obviously push hard assured-intelligence, control-orchestration, or user-defined custom-policy work onto the local model.
7. In observation mode, stop after presenting the recommendation unless the user explicitly asks to apply it.
8. If the user explicitly approves an edit, update ~/.openclaw/openclaw.json, then restart the OpenClaw gateway.
9. Report exactly what changed and why, using the log summary as evidence.

Heuristics

• Too many cost-optimized-solving decisions with low complex margin: raise thresholds.complexMinScore.
• Too few assured-intelligence decisions while many prompts are just below codeMinScore: lower thresholds.codeMinScore slightly, or raise weights.filePath / weights.codeFence.
• Too few control-orchestration decisions while prompts have strong reasoning words: lower thresholds.reasoningMinScore or raise weights.reasoningKeyword.
• Too many short prompts still landing in cost-optimized-solving: raise weights.simpleKeyword or add better keywords.simple.
• Poor fallback proximity: add models to fallbacks.extraModels only if they are actually configured and available.
• API usage reduction should be estimated as request-count reduction: local = 0 cost, non-local = 1 API usage unit per request.
• Prefer recommendations that move borderline cost-optimized-solving traffic to the efficient-response local tier. Those are the clearest zero-cost savings.
• Treat this as a cost-optimizer, not an autonomous self-rewriting system. The default output should be recommendation quality, not aggressive automation.

Commands

Run the analyzer first:

node skills/router-rule-tuner/scripts/analyze_router_logs.mjs

Custom log path:

node skills/router-rule-tuner/scripts/analyze_router_logs.mjs '/custom/path/router.jsonl'

Note: The plugin now includes a built-in /router learn command that provides similar analysis with automatic weight learning. This skill is still useful for more detailed, manual tuning with human review.

Output expectations

When using this skill, provide:

• the current routing skew,
• the current local/API split,
• the concrete config edits you recommend,
• the predicted API usage before and after each recommendation,
• the reason for each edit,
• and any remaining uncertainty because the logs do not yet capture user satisfaction directly.