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: INLINECODE0
- 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
CODEBLOCK0
Inference strategy is auto-selected by GPU availability:
| Strategy | Trigger | Model | Approach |
|---|
| INLINECODE2 | GPU available | INLINECODE3 | Deep semantic summarization |
| INLINECODE4 |
CPU only |
phi3.5:3b | Extractive bullet points |
|
passthrough | Ollama unreachable | — | Truncate to last 20 lines |
Install
Step 1 — Install the plugin
CODEBLOCK1
To pin an exact version:
CODEBLOCK2
Step 2 — First-time setup
CODEBLOCK3
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
CODEBLOCK4
Step 4 — Verify
CODEBLOCK5
Should show current settings and sidecar status (reachable / unreachable).
Configuration
Set config values with:
CODEBLOCK6
| Key | Default | Description |
|---|
| INLINECODE7 | INLINECODE8 | TokenRanger sidecar URL |
| INLINECODE9 |
10000 | Max wait before fallthrough |
|
minPromptLength |
500 | Min chars before compressing |
|
ollamaUrl |
http://127.0.0.1:11434 | Ollama API URL |
|
preferredModel |
mistral:7b | Model for GPU strategy |
|
compressionStrategy |
auto |
auto /
full /
light /
passthrough |
|
inferenceMode |
auto |
auto /
cpu /
gpu /
remote |
Force CPU-only mode:
CODEBLOCK7
Commands
| Command | Description |
|---|
| INLINECODE29 | Show current settings and sidecar health |
| INLINECODE30 |
Force GPU (full) compression |
|
/tokenranger mode cpu | Force CPU (light) compression |
|
/tokenranger mode off | Disable compression (passthrough) |
|
/tokenranger model | List available Ollama models |
|
/tokenranger toggle | Enable / disable the plugin |
Upgrading
CODEBLOCK8
To pin a specific version:
CODEBLOCK9
List all published versions:
CODEBLOCK10
Uninstalling
CODEBLOCK11
Remove the sidecar service manually:
CODEBLOCK12
Troubleshooting
Sidecar unreachable after setup:
CODEBLOCK13
Ollama not found:
CODEBLOCK14
Compression not reducing tokens:
- - Check
minPromptLength — default 500 chars; short conversations are skipped by design - Run
/tokenranger to confirm strategy is not INLINECODE37 - 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):
| Turn | Input tokens | Compressed | Reduction |
|---|
| 2 | 732 | 125 | 82.9% |
| 3 |
1,180 | 150 | 87.3% |
| 4 | 1,685 | 212 | 87.4% |
| 5 | 2,028 | 277 | 86.3% |
Cumulative: 5,866 → 885 tokens (84.9% reduction)
TokenRanger
TokenRanger 通过本地 Ollama SLM 压缩会话上下文，然后再发送至云端大语言模型——每轮对话可减少 50–80% 的输入令牌成本，且具备优雅降级机制，确保任何异常情况下都能正常回退。
- - 插件仓库： https://github.com/peterjohannmedina/openclaw-plugin-tokenranger
- npm： openclaw-plugin-tokenranger
- 维护者： @peterjohannmedina
何时加载此技能
- - 用户要求安装、配置或排查 TokenRanger 问题
- 用户希望降低令牌成本或启用上下文压缩
- 用户运行 /tokenranger 命令并需要帮助解读输出结果
- 用户想要切换压缩策略（GPU/CPU/关闭）
- 用户询问升级或卸载 TokenRanger
工作原理
用户消息 → OpenClaw 网关
→ beforeagentstart 钩子
→ 第1轮：跳过（完整保真度）
→ 第2轮起：将历史记录发送至 localhost:8100/compress
→ FastAPI 边车通过 Ollama 运行 LangChain LCEL 链
→ 压缩摘要前置到上下文中
→ 云端大语言模型接收压缩后的上下文，而非完整历史记录
推理策略根据 GPU 可用性自动选择：
| 策略 | 触发条件 | 模型 | 方式 |
|---|
| full | GPU 可用 | mistral:7b | 深度语义摘要 |
| light |
仅 CPU | phi3.5:3b | 提取式要点 |
| passthrough | Ollama 不可达 | — | 截断至最后20行 |
安装
步骤 1 — 安装插件
bash
openclaw plugins install openclaw-plugin-tokenranger
固定特定版本：
bash
openclaw plugins install openclaw-plugin-tokenranger@1.0.0 --pin
步骤 2 — 首次设置
bash
openclaw tokenranger setup
此命令将拉取 Ollama 模型、创建 Python 虚拟环境、安装 FastAPI/LangChain 依赖，并将边车注册为系统服务（Linux 上为 systemd，macOS 上为 launchd）。
步骤 3 — 重启网关
bash
openclaw gateway restart
步骤 4 — 验证
bash
openclaw tokenranger
应显示当前设置和边车状态（可达/不可达）。
配置
使用以下命令设置配置值：
bash
openclaw config set plugins.entries.tokenranger.config.
openclaw gateway restart
| 键 | 默认值 | 描述 |
|---|
| serviceUrl | http://127.0.0.1:8100 | TokenRanger 边车 URL |
| timeoutMs |
10000 | 回退前的最大等待时间 |
| minPromptLength | 500 | 开始压缩的最小字符数 |
| ollamaUrl | http://127.0.0.1:11434 | Ollama API URL |
| preferredModel | mistral:7b | GPU 策略使用的模型 |
| compressionStrategy | auto | auto / full / light / passthrough |
| inferenceMode | auto | auto / cpu / gpu / remote |
强制仅 CPU 模式：
bash
openclaw config set plugins.entries.tokenranger.config.compressionStrategy light
openclaw config set plugins.entries.tokenranger.config.inferenceMode cpu
openclaw gateway restart
命令
| 命令 | 描述 |
|---|
| /tokenranger | 显示当前设置和边车健康状态 |
| /tokenranger mode gpu |
强制 GPU（完整）压缩 |
| /tokenranger mode cpu | 强制 CPU（精简）压缩 |
| /tokenranger mode off | 禁用压缩（直通模式） |
| /tokenranger model | 列出可用的 Ollama 模型 |
| /tokenranger toggle | 启用/禁用插件 |
升级
bash
检查更新（预演）
openclaw plugins update tokenranger --dry-run
应用更新
openclaw plugins update tokenranger
openclaw tokenranger setup # 如果边车依赖发生变化，重新运行设置
openclaw gateway restart
固定特定版本：
bash
openclaw plugins install openclaw-plugin-tokenranger@2026.3.1 --pin
openclaw tokenranger setup
openclaw gateway restart
列出所有已发布版本：
bash
npm view openclaw-plugin-tokenranger versions --json
卸载
bash
openclaw plugins uninstall tokenranger
openclaw gateway restart
手动移除边车服务：
bash
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
故障排除
设置后边车不可达：
bash
Linux
systemctl --user status tokenranger
journalctl --user -u tokenranger -n 50
macOS
launchctl list | grep tokenranger
cat ~/Library/Logs/tokenranger.log
手动启动（任意平台）
~/.openclaw/extensions/tokenranger/service/start.sh
找不到 Ollama：
bash
curl http://127.0.0.1:11434/api/tags
如果未运行：
ollama serve
压缩未减少令牌数：
- - 检查 minPromptLength — 默认为500字符；短对话按设计会被跳过
- 运行 /tokenranger 确认策略不是 passthrough
- 检查边车日志中的错误信息
优雅降级： TokenRanger 绝不会阻塞消息。任何故障 → 静默回退至未压缩的云端大语言模型调用。
性能参考
5轮 Discord 基准测试（GPU，mistral:7b-instruct）：
| 轮次 | 输入令牌数 | 压缩后 | 减少比例 |
|---|
| 2 | 732 | 125 | 82.9% |
| 3 |
1,180 | 150 | 87.3% |
| 4 | 1,685 | 212 | 87.4% |
| 5 | 2,028 | 277 | 86.3% |
累计：5,866 → 885 令牌（减少 84.9%）
