# Send TokenRanger to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - 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. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text 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. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "tokenranger", "name": "TokenRanger", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/synchronic1/tokenranger", "canonicalUrl": "https://clawhub.ai/synchronic1/tokenranger", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/tokenranger", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tokenranger", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "tokenranger", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-04T04:04:34.969Z", "expiresAt": "2026-05-11T04:04:34.969Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tokenranger", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tokenranger", "contentDisposition": "attachment; filename=\"tokenranger-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "tokenranger" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/tokenranger" }, "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." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/tokenranger", "downloadUrl": "https://openagent3.xyz/downloads/tokenranger", "agentUrl": "https://openagent3.xyz/skills/tokenranger/agent", "manifestUrl": "https://openagent3.xyz/skills/tokenranger/agent.json", "briefUrl": "https://openagent3.xyz/skills/tokenranger/agent.md" } } ``` ## Documentation ### TokenRanger TokenRanger compresses session context through a local Ollama SLM before sending to cloud LLMs — reducing input token costs by 50–80% per turn with graceful fallthrough if anything goes wrong. Plugin repo: https://github.com/peterjohannmedina/openclaw-plugin-tokenranger npm: openclaw-plugin-tokenranger Maintained by: @peterjohannmedina ### When to Load This Skill User asks to install, configure, or troubleshoot TokenRanger User wants to reduce token costs or enable context compression User runs /tokenranger commands and needs help interpreting output User wants to switch compression strategy (GPU/CPU/off) User asks about upgrading or uninstalling TokenRanger ### How It Works User message → OpenClaw gateway → before_agent_start hook → Turn 1: skip (full fidelity) → Turn 2+: send history to localhost:8100/compress → FastAPI sidecar runs LangChain LCEL chain via Ollama → Compressed summary prepended to context → Cloud LLM receives compressed context instead of full history Inference strategy is auto-selected by GPU availability: StrategyTriggerModelApproachfullGPU availablemistral:7bDeep semantic summarizationlightCPU onlyphi3.5:3bExtractive bullet pointspassthroughOllama unreachable—Truncate to last 20 lines ### Step 1 — Install the plugin openclaw plugins install openclaw-plugin-tokenranger To pin an exact version: openclaw plugins install openclaw-plugin-tokenranger@1.0.0 --pin ### Step 2 — First-time setup openclaw tokenranger setup This pulls Ollama models, creates the Python venv, installs FastAPI/LangChain deps, and registers the sidecar as a system service (systemd on Linux, launchd on macOS). ### Step 3 — Restart gateway openclaw gateway restart ### Step 4 — Verify openclaw tokenranger Should show current settings and sidecar status (reachable / unreachable). ### Configuration Set config values with: openclaw config set plugins.entries.tokenranger.config. openclaw gateway restart KeyDefaultDescriptionserviceUrlhttp://127.0.0.1:8100TokenRanger sidecar URLtimeoutMs10000Max wait before fallthroughminPromptLength500Min chars before compressingollamaUrlhttp://127.0.0.1:11434Ollama API URLpreferredModelmistral:7bModel for GPU strategycompressionStrategyautoauto / full / light / passthroughinferenceModeautoauto / cpu / gpu / remote Force CPU-only mode: openclaw config set plugins.entries.tokenranger.config.compressionStrategy light openclaw config set plugins.entries.tokenranger.config.inferenceMode cpu openclaw gateway restart ### Commands CommandDescription/tokenrangerShow current settings and sidecar health/tokenranger mode gpuForce GPU (full) compression/tokenranger mode cpuForce CPU (light) compression/tokenranger mode offDisable compression (passthrough)/tokenranger modelList available Ollama models/tokenranger toggleEnable / disable the plugin ### Upgrading # Check for updates (dry run) openclaw plugins update tokenranger --dry-run # Apply update openclaw plugins update tokenranger openclaw tokenranger setup # re-runs setup if sidecar deps changed openclaw gateway restart To pin a specific version: openclaw plugins install openclaw-plugin-tokenranger@2026.3.1 --pin openclaw tokenranger setup openclaw gateway restart List all published versions: npm view openclaw-plugin-tokenranger versions --json ### Uninstalling openclaw plugins uninstall tokenranger openclaw gateway restart Remove the sidecar service manually: # Linux systemctl --user stop tokenranger && systemctl --user disable tokenranger rm ~/.config/systemd/user/tokenranger.service # macOS launchctl unload ~/Library/LaunchAgents/com.peterjohannmedina.tokenranger.plist rm ~/Library/LaunchAgents/com.peterjohannmedina.tokenranger.plist ### Troubleshooting Sidecar unreachable after setup: # Linux systemctl --user status tokenranger journalctl --user -u tokenranger -n 50 # macOS launchctl list | grep tokenranger cat ~/Library/Logs/tokenranger.log # Manual start (any platform) ~/.openclaw/extensions/tokenranger/service/start.sh Ollama not found: curl http://127.0.0.1:11434/api/tags # If not running: ollama serve Compression not reducing tokens: Check minPromptLength — default 500 chars; short conversations are skipped by design Run /tokenranger to confirm strategy is not passthrough Check sidecar logs for errors Graceful degradation: TokenRanger never blocks a message. Any failure → silent fallthrough to uncompressed cloud LLM call. ### Performance Reference 5-turn Discord benchmark (GPU, mistral:7b-instruct): TurnInput tokensCompressedReduction273212582.9%31,18015087.3%41,68521287.4%52,02827786.3% Cumulative: 5,866 → 885 tokens (84.9% reduction) ## Trust - Source: tencent - Verification: Indexed source record - Publisher: synchronic1 - Version: 1.0.0 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-05-04T04:04:34.969Z - Expires at: 2026-05-11T04:04:34.969Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/tokenranger) - [Send to Agent page](https://openagent3.xyz/skills/tokenranger/agent) - [JSON manifest](https://openagent3.xyz/skills/tokenranger/agent.json) - [Markdown brief](https://openagent3.xyz/skills/tokenranger/agent.md) - [Download page](https://openagent3.xyz/downloads/tokenranger)