OpenClaw Context Meter Plugin Shows Telegram Token Usage Percentage

What It Does

The openclaw-context-meter plugin automatically shows token usage percentage after every Telegram bot response. After each response, it sends a small footer like: 📊 45k / 200k (22%). When compaction happens (tokens drop significantly), it shows: 📊 30k / 200k (15%) — compacted from 150k.

The Problem It Solves

Previously, there was no easy way to see how full the context window is without constantly typing /status. The plugin provides automatic visibility into token consumption.

Development Journey

v1 — The OOM Disaster: Initially used execSync("openclaw models list --json") to dynamically discover model context windows. This spawned a full OpenClaw process (~2GB RAM) every time the plugin loaded. With the plugin loading 4-5 times at startup (once per agent/runtime), this caused: 2GB gateway + 5 × 2GB subprocesses = 12GB → instant OOM. The OOM killer took out sshd and NetworkManager, making servers completely unreachable, creating an infinite restart loop.

v2 — The Lightweight Fix: Hardcoded context windows for 40+ models. Zero subprocesses, zero memory overhead. Key realization: never use execSync in OpenClaw plugins, as even a simple CLI query spawns the entire runtime with all plugins and TypeScript compilation.

Why No Fork Needed

The plugin originally forked OpenClaw to patch before_compaction/after_compaction hooks, but upstream changes made this unnecessary:

• v2026.3.13+ — upstream now passes sessionId + agentId + sessionKey in compaction hook context
• v2026.3.22+ — built-in 🧹 Compacting context... notifications (issue #38805) made their compaction code unnecessary
• v2026.3.22+ — built-in /usage tokens|full|cost command for basic token display

The plugin now focuses on what's still missing: context window percentage display.

Features

• Zero-cost — uses agent_end + message_sent hooks only, no extra API calls
• No subprocesses — model context windows are hardcoded (no execSync OOM risk)
• Smart filtering — skips tool_use turns, only sends footer after final text response
• Debounced — waits 1.5s after last message to avoid footer mid-stream
• Multi-agent — works with multiple agents and Telegram accounts
• Compaction detection — detects token drops and shows before/after stats

Known Limitations

• Some providers (like Qwen) return totalTokens: 0 — footer won't show for those models
• Hardcoded context windows might be wrong for newer models — pulled from v2026.3.22 source
• Telegram only for now (sends footer via Bot API)

Installation

cd ~/.openclaw/extensions
npm pack openclaw-context-meter
tar xzf openclaw-context-meter-*.tgz
mv package context-meter
rm openclaw-context-meter-*.tgz

Add to openclaw.json:

{
  "plugins": {
    "allow": ["context-meter"],
    "entries": {
      "context-meter": {
        "enabled": true
      }
    }
  }
}

Requires OpenClaw >= 2026.3.22.