home / skills / openclaw / skills / mkhaytman-token-optimizer

mkhaytman-token-optimizer skill

safe

/skills/mkhaytman87/mkhaytman-token-optimizer

This skill analyzes and reduces token waste with local compression, health checks, and preflight budgeting to optimize OpenClaw sessions.

npx playbooks add skill openclaw/skills --skill mkhaytman-token-optimizer

Review the files below or copy the command above to add this skill to your agents.

Files (13)

SKILL.md

2.7 KB

---
name: token-optimizer
description: Automatically analyze and reduce OpenClaw token waste through context compression, tool-call deduplication insights, model selection guidance, and session hygiene checks. Use when sessions are nearing context limits, costs are climbing, or you want proactive token optimization before expensive tasks.
---

# Token Optimizer

## Overview

Use this skill to optimize OpenClaw token usage with a local CLI that performs analysis, compression snapshots, health checks, cleanup planning, and preflight token budgeting.

## Quick Start

```bash
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize --analyze --period 7d
```

## Core Commands

1) Enable local optimizer config:

```bash
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize --enable
```

2) Optimization analysis:

```bash
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize --analyze --period 7d
```

3) Force context compression snapshot:

```bash
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize --compress --threshold 0.7 --session agent:main:main
```

4) Session health check:

```bash
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize --health-check --active-minutes 120
```

5) Auto-cleanup planning and apply:

```bash
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize --cleanup
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize --cleanup --apply
```

## Preflight Optimization

Use preflight planning before expensive task batches:

```bash
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize \
  --preflight /path/to/actions.json \
  --session-limit 180000
```

`actions.json` should be a JSON array of planned operations, for example:

```json
[
  {"type": "web_search", "query": "..."},
  {"type": "web_fetch", "url": "..."},
  {"type": "summarize", "target": "youtube"}
]
```

## Output Artifacts

- Compression snapshots: `$OPENCLAW_WORKSPACE/token-usage/compressed/`
- Optional JSON output: `--format json --output /path/file.json`
- Baseline config (from `--enable`): `$OPENCLAW_WORKSPACE/token-usage/token-optimizer.config.json`

## Defaults

Default behavior is configured in:

- `config/defaults.json`

Override with:

```bash
$OPENCLAW_SKILLS_DIR/token-optimizer/scripts/token-optimize --config /path/custom.json --analyze
```

## Resources

- `scripts/token_optimize.py`: main CLI
- `src/optimizer.py`: core optimization engine
- `src/models.py`: model selection logic
- `src/compression.py`: context compression helpers
- `src/cleanup.py`: session hygiene evaluation
- `references/operating-notes.md`: implementation details and safe-operating guidance

## Validation

```bash
python3 $OPENCLAW_SKILLS_DIR/.system/skill-creator/scripts/quick_validate.py \
  $OPENCLAW_SKILLS_DIR/token-optimizer
```

Overview

This skill automatically analyzes and reduces OpenClaw token waste through context compression, tool-call deduplication, model selection guidance, and session hygiene checks. It provides a local CLI for snapshots, preflight budgeting, health checks, and cleanup planning to keep sessions under context limits and reduce costs. Use it when token usage approaches platform limits or when you want proactive optimization before large workloads.

How this skill works

The CLI scans recent sessions and operations to identify high-cost context segments, duplicated tool calls, and inefficient model choices. It produces compression snapshots, recommends model switches, and generates cleanup plans or applies safe deletions. For planned operation batches it simulates token consumption and returns preflight budgets and risk flags. Outputs include JSON reports and stored compression artifacts for auditability.

When to use it

Sessions are nearing context length or token quota limits.
Monthly or per-job costs are rising and need investigation.
Before running large or expensive batches of actions.
To enforce session hygiene and remove stale context.
When you want automated guidance on cheaper model choices.

Best practices

Run periodic analyses (e.g., weekly) to catch regressions early.
Use preflight mode for any planned multi-step operation batch.
Keep baseline config checked into your workspace for repeatability.
Review compression snapshots before applying automatic cleanup.
Prefer model guidance recommendations that balance cost and accuracy.

Example use cases

Analyze the last 7 days of agent sessions to find redundant tool calls and compress long contexts.
Simulate token needs for an upcoming batch of web fetches and summaries to estimate budget.
Force a compression snapshot on a high-memory session that blocks new activity.
Run a health check to flag sessions idle beyond a safe threshold and plan cleanup.
Generate a JSON report of token usage trends to present to engineering or finance.

FAQ

Will the skill delete session data automatically?

It only deletes data when you explicitly run cleanup with the --apply flag; analysis and plans are read-only by default.

Can it recommend cheaper models without losing quality?

Yes. The model selection guidance highlights lower-cost alternatives and flags potential accuracy trade-offs so you can choose.