{
  "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": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/tokenranger",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=tokenranger",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "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."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "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."
        },
        {
          "label": "Upgrade existing",
          "body": "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."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "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."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/tokenranger",
    "agentPageUrl": "https://openagent3.xyz/skills/tokenranger/agent",
    "manifestUrl": "https://openagent3.xyz/skills/tokenranger/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/tokenranger/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "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."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "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."
      },
      {
        "label": "Upgrade existing",
        "body": "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."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "TokenRanger",
        "body": "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.\n\nPlugin repo: https://github.com/peterjohannmedina/openclaw-plugin-tokenranger\nnpm: openclaw-plugin-tokenranger\nMaintained by: @peterjohannmedina"
      },
      {
        "title": "When to Load This Skill",
        "body": "User asks to install, configure, or troubleshoot TokenRanger\nUser wants to reduce token costs or enable context compression\nUser runs /tokenranger commands and needs help interpreting output\nUser wants to switch compression strategy (GPU/CPU/off)\nUser asks about upgrading or uninstalling TokenRanger"
      },
      {
        "title": "How It Works",
        "body": "User message → OpenClaw gateway\n  → before_agent_start hook\n  → Turn 1: skip (full fidelity)\n  → Turn 2+: send history to localhost:8100/compress\n  → FastAPI sidecar runs LangChain LCEL chain via Ollama\n  → Compressed summary prepended to context\n  → Cloud LLM receives compressed context instead of full history\n\nInference strategy is auto-selected by GPU availability:\n\nStrategyTriggerModelApproachfullGPU availablemistral:7bDeep semantic summarizationlightCPU onlyphi3.5:3bExtractive bullet pointspassthroughOllama unreachable—Truncate to last 20 lines"
      },
      {
        "title": "Step 1 — Install the plugin",
        "body": "openclaw plugins install openclaw-plugin-tokenranger\n\nTo pin an exact version:\n\nopenclaw plugins install openclaw-plugin-tokenranger@1.0.0 --pin"
      },
      {
        "title": "Step 2 — First-time setup",
        "body": "openclaw tokenranger setup\n\nThis pulls Ollama models, creates the Python venv, installs FastAPI/LangChain deps,\nand registers the sidecar as a system service (systemd on Linux, launchd on macOS)."
      },
      {
        "title": "Step 3 — Restart gateway",
        "body": "openclaw gateway restart"
      },
      {
        "title": "Step 4 — Verify",
        "body": "openclaw tokenranger\n\nShould show current settings and sidecar status (reachable / unreachable)."
      },
      {
        "title": "Configuration",
        "body": "Set config values with:\n\nopenclaw config set plugins.entries.tokenranger.config.<key> <value>\nopenclaw gateway restart\n\nKeyDefaultDescriptionserviceUrlhttp://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\n\nForce CPU-only mode:\n\nopenclaw config set plugins.entries.tokenranger.config.compressionStrategy light\nopenclaw config set plugins.entries.tokenranger.config.inferenceMode cpu\nopenclaw gateway restart"
      },
      {
        "title": "Commands",
        "body": "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"
      },
      {
        "title": "Upgrading",
        "body": "# Check for updates (dry run)\nopenclaw plugins update tokenranger --dry-run\n\n# Apply update\nopenclaw plugins update tokenranger\nopenclaw tokenranger setup   # re-runs setup if sidecar deps changed\nopenclaw gateway restart\n\nTo pin a specific version:\n\nopenclaw plugins install openclaw-plugin-tokenranger@2026.3.1 --pin\nopenclaw tokenranger setup\nopenclaw gateway restart\n\nList all published versions:\n\nnpm view openclaw-plugin-tokenranger versions --json"
      },
      {
        "title": "Uninstalling",
        "body": "openclaw plugins uninstall tokenranger\nopenclaw gateway restart\n\nRemove the sidecar service manually:\n\n# Linux\nsystemctl --user stop tokenranger && systemctl --user disable tokenranger\nrm ~/.config/systemd/user/tokenranger.service\n\n# macOS\nlaunchctl unload ~/Library/LaunchAgents/com.peterjohannmedina.tokenranger.plist\nrm ~/Library/LaunchAgents/com.peterjohannmedina.tokenranger.plist"
      },
      {
        "title": "Troubleshooting",
        "body": "Sidecar unreachable after setup:\n\n# Linux\nsystemctl --user status tokenranger\njournalctl --user -u tokenranger -n 50\n\n# macOS\nlaunchctl list | grep tokenranger\ncat ~/Library/Logs/tokenranger.log\n\n# Manual start (any platform)\n~/.openclaw/extensions/tokenranger/service/start.sh\n\nOllama not found:\n\ncurl http://127.0.0.1:11434/api/tags\n# If not running:\nollama serve\n\nCompression not reducing tokens:\n\nCheck minPromptLength — default 500 chars; short conversations are skipped by design\nRun /tokenranger to confirm strategy is not passthrough\nCheck sidecar logs for errors\n\nGraceful degradation: TokenRanger never blocks a message. Any failure → silent fallthrough to uncompressed cloud LLM call."
      },
      {
        "title": "Performance Reference",
        "body": "5-turn Discord benchmark (GPU, mistral:7b-instruct):\n\nTurnInput tokensCompressedReduction273212582.9%31,18015087.3%41,68521287.4%52,02827786.3%\n\nCumulative: 5,866 → 885 tokens (84.9% reduction)"
      }
    ],
    "body": "TokenRanger\n\nTokenRanger 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.\n\nPlugin repo: https://github.com/peterjohannmedina/openclaw-plugin-tokenranger\nnpm: openclaw-plugin-tokenranger\nMaintained by: @peterjohannmedina\nWhen to Load This Skill\nUser asks to install, configure, or troubleshoot TokenRanger\nUser wants to reduce token costs or enable context compression\nUser runs /tokenranger commands and needs help interpreting output\nUser wants to switch compression strategy (GPU/CPU/off)\nUser asks about upgrading or uninstalling TokenRanger\nHow It Works\nUser message → OpenClaw gateway\n  → before_agent_start hook\n  → Turn 1: skip (full fidelity)\n  → Turn 2+: send history to localhost:8100/compress\n  → FastAPI sidecar runs LangChain LCEL chain via Ollama\n  → Compressed summary prepended to context\n  → Cloud LLM receives compressed context instead of full history\n\n\nInference strategy is auto-selected by GPU availability:\n\nStrategy\tTrigger\tModel\tApproach\nfull\tGPU available\tmistral:7b\tDeep semantic summarization\nlight\tCPU only\tphi3.5:3b\tExtractive bullet points\npassthrough\tOllama unreachable\t—\tTruncate to last 20 lines\nInstall\nStep 1 — Install the plugin\nopenclaw plugins install openclaw-plugin-tokenranger\n\n\nTo pin an exact version:\n\nopenclaw plugins install openclaw-plugin-tokenranger@1.0.0 --pin\n\nStep 2 — First-time setup\nopenclaw tokenranger setup\n\n\nThis 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).\n\nStep 3 — Restart gateway\nopenclaw gateway restart\n\nStep 4 — Verify\nopenclaw tokenranger\n\n\nShould show current settings and sidecar status (reachable / unreachable).\n\nConfiguration\n\nSet config values with:\n\nopenclaw config set plugins.entries.tokenranger.config.<key> <value>\nopenclaw gateway restart\n\nKey\tDefault\tDescription\nserviceUrl\thttp://127.0.0.1:8100\tTokenRanger sidecar URL\ntimeoutMs\t10000\tMax wait before fallthrough\nminPromptLength\t500\tMin chars before compressing\nollamaUrl\thttp://127.0.0.1:11434\tOllama API URL\npreferredModel\tmistral:7b\tModel for GPU strategy\ncompressionStrategy\tauto\tauto / full / light / passthrough\ninferenceMode\tauto\tauto / cpu / gpu / remote\n\nForce CPU-only mode:\n\nopenclaw config set plugins.entries.tokenranger.config.compressionStrategy light\nopenclaw config set plugins.entries.tokenranger.config.inferenceMode cpu\nopenclaw gateway restart\n\nCommands\nCommand\tDescription\n/tokenranger\tShow current settings and sidecar health\n/tokenranger mode gpu\tForce GPU (full) compression\n/tokenranger mode cpu\tForce CPU (light) compression\n/tokenranger mode off\tDisable compression (passthrough)\n/tokenranger model\tList available Ollama models\n/tokenranger toggle\tEnable / disable the plugin\nUpgrading\n# Check for updates (dry run)\nopenclaw plugins update tokenranger --dry-run\n\n# Apply update\nopenclaw plugins update tokenranger\nopenclaw tokenranger setup   # re-runs setup if sidecar deps changed\nopenclaw gateway restart\n\n\nTo pin a specific version:\n\nopenclaw plugins install openclaw-plugin-tokenranger@2026.3.1 --pin\nopenclaw tokenranger setup\nopenclaw gateway restart\n\n\nList all published versions:\n\nnpm view openclaw-plugin-tokenranger versions --json\n\nUninstalling\nopenclaw plugins uninstall tokenranger\nopenclaw gateway restart\n\n\nRemove the sidecar service manually:\n\n# Linux\nsystemctl --user stop tokenranger && systemctl --user disable tokenranger\nrm ~/.config/systemd/user/tokenranger.service\n\n# macOS\nlaunchctl unload ~/Library/LaunchAgents/com.peterjohannmedina.tokenranger.plist\nrm ~/Library/LaunchAgents/com.peterjohannmedina.tokenranger.plist\n\nTroubleshooting\n\nSidecar unreachable after setup:\n\n# Linux\nsystemctl --user status tokenranger\njournalctl --user -u tokenranger -n 50\n\n# macOS\nlaunchctl list | grep tokenranger\ncat ~/Library/Logs/tokenranger.log\n\n# Manual start (any platform)\n~/.openclaw/extensions/tokenranger/service/start.sh\n\n\nOllama not found:\n\ncurl http://127.0.0.1:11434/api/tags\n# If not running:\nollama serve\n\n\nCompression not reducing tokens:\n\nCheck minPromptLength — default 500 chars; short conversations are skipped by design\nRun /tokenranger to confirm strategy is not passthrough\nCheck sidecar logs for errors\n\nGraceful degradation: TokenRanger never blocks a message. Any failure → silent fallthrough to uncompressed cloud LLM call.\n\nPerformance Reference\n\n5-turn Discord benchmark (GPU, mistral:7b-instruct):\n\nTurn\tInput tokens\tCompressed\tReduction\n2\t732\t125\t82.9%\n3\t1,180\t150\t87.3%\n4\t1,685\t212\t87.4%\n5\t2,028\t277\t86.3%\n\nCumulative: 5,866 → 885 tokens (84.9% reduction)"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/synchronic1/tokenranger",
    "publisherUrl": "https://clawhub.ai/synchronic1/tokenranger",
    "owner": "synchronic1",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "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"
  }
}