什么是 tokenQrusher？

tokenQrusher 是专为 Openclaw Skills 生态系统设计的专用工具，旨在解决与大语言模型 API 使用相关的高昂成本问题。它作为中间层运行，拦截智能体引导事件，确保仅将最相关的上下文发送到模型。通过将用户提示分为不同的复杂度级别，对于简单交互，它可以减少高达 99% 的 Token 开销，同时保留复杂工程任务的完整能力。

除上下文管理外，该技能还优化了 AI 智能体的后台心跳频率。这可以防止在进行电子邮件或日历坚控等周期性检查时产生不必要的 API 调用，从而进一步降低成本并提高系统效率。tokenQrusher 在构建时充分考虑了性能，以亚毫秒级的延迟运行，并使用确定性逻辑确保本地环境内可靠、线程安全的执行。

下载入口:https://github.com/openclaw/skills/tree/main/skills/qsmtco/tokenqrusher

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

tokenQrusher 应用场景

• 在 GPT-4 或 Claude 3 Opus 等昂贵模型上运行 AI 智能体时降低运营成本。
• 通过减少大模型处理简单查询时所需的上下文量来缩短响应时间。
• 通过智能间隔心跳和坚控调用来管理 API 速率限制。
• 根据任务选择性地加载身份或工具文件，自定义智能体的人设可见性。
• 为自动化智能体实施静默时间，防止非工作时段的后台活动。

1. 系统在每条用户消息的 agent:bootstrap 事件期间触发 token-context 钩子。
2. 分类引擎分析用户提示，以确定其是简单、标准还是复杂级别。
3. 根据提示复杂度，该技能会过滤工作区文件列表，仅包含本地配置中定义的文件。
4. 同时，token-heartbeat 钩子根据自定义间隔和静默时间设置，评估计划的后台任务是否到期。
5. 如果检查尚未到期或处于静默时间内，系统将返回跳过 API 调用的状态。
6. 最终优化的上下文和心跳计划将传回网关供智能体执行。

tokenQrusher 配置指南

要将此优化层集成到您的 Openclaw Skills 设置中，请遵循以下安装步骤：

# 从枢纽安装技能
clawhub install tokenQrusher

# 启用上下文和心跳钩子
tokenqrusher install --hooks

# 验证安装状态
tokenqrusher status

# 重启 OpenClaw 网关以应用优化
openclaw gateway restart

确保您已安装 python3 和 node 作为核心模块的先决条件。

tokenQrusher 数据架构与分类体系

该技能利用本地 JSON 配置文件来定义优化规则，确保数据绝不会离开您的系统。这符合 Openclaw Skills 的安全标准。

name: tokenQrusher
description: Token optimization system for OpenClaw reducing costs 50-80%
version: 2.1.1
author: qsmtco
license: MIT
homepage: https://github.com/qsmtco/tokenQrusher
metadata:
  openclaw:
    requires:
      bins:
        - python3
        - node
    emoji: "??"

tokenQrusher Skill

Overview

tokenQrusher reduces OpenClaw API costs by 50-80% through:

1. Context Filtering – Loads only necessary workspace files (up to 99% reduction for simple messages)
2. Heartbeat Optimization – Reduces heartbeat API calls by 75%

This is the simplified, production-ready core. Non-functional advisory components have been removed.

Components

1. Context Hook (token-context)

Event: agent:bootstrap

Filters which workspace files are loaded based on message complexity.

Config: ~/.openclaw/hooks/token-context/config.json

{
  "enabled": true,
  "logLevel": "info",
  "dryRun": false,
  "files": {
    "simple": ["SOUL.md", "IDENTITY.md"],
    "standard": ["SOUL.md", "IDENTITY.md", "USER.md"],
    "complex": ["SOUL.md", "IDENTITY.md", "USER.md", "TOOLS.md", "AGENTS.md", "MEMORY.md", "HEARTBEAT.md"]
  }
}

How it works:

• Extracts the user's latest message
• Classifies complexity (simple/standard/complex)
• Keeps only allowed files, discards the rest
• Sets context.bootstrapFiles to the filtered list

Savings:

• Simple greetings → 2 files (99% token reduction)
• Standard tasks → 3 files (90%+ reduction)
• Complex tasks → all files (full context)

Rationale: Simple messages don’t need documentation, memory logs, or tool references. Only identity and personality are required.

2. Heartbeat Optimizer (token-heartbeat)

Event: agent:bootstrap (for heartbeat polls)

Optimizes heartbeat check schedule to dramatically reduce API calls.

Config: ~/.openclaw/hooks/token-heartbeat/config.json

{
  "enabled": true,
  "intervals": {
    "email": 7200,
    "calendar": 14400,
    "weather": 14400,
    "monitoring": 7200
  },
  "quietHours": { "start": 23, "end": 8 }
}

How it works:

• Determines if enough time has elapsed since last check
• Skips checks that are not due
• Honors quiet hours (23:00–08:00 by default)
• Returns HEARTBEAT_OK when nothing needs checking

Optimization Table:

Result: 48 checks/day → 12 checks/day (75% fewer API calls)

3. Shared Module (token-shared)

Pure functions used by both hooks:

• classifyComplexity(message) → complexity level
• getAllowedFiles(level, config) → file list
• isValidFileName(name) → path traversal protection
• loadConfigCached(logFn) → 60s TTL config caching
• Maybe/Either patterns (no exceptions for control flow)

External Endpoints

This skill does not call any external network endpoints. All operations are local to your machine.

Security & Privacy

• 100% local execution – No data leaves your system.
• No external telemetry – No calls to third?party servers.
• Configuration read only from local hook configs.
• File validation prevents path traversal attacks.
• No environment secrets required.

Model Invocation Note

Hooks run automatically:

• token-context runs on every agent:bootstrap (every user message).
• token-heartbeat runs on heartbeat polls. No manual intervention needed after enabling the hooks.

Trust Statement

By installing this skill, you trust that the code operates locally and does not transmit your workspace data. Review the open?source implementation on GitHub before installing.

CLI Commands

After installation, the tokenqrusher command is available.

tokenqrusher context

Recommends which context files should be loaded for a given prompt.

$ tokenqrusher context "hi"
Complexity: simple (confidence: 95%)
Files: SOUL.md, IDENTITY.md
Savings: 71%

tokenqrusher status [--verbose]

Shows system status.

$ tokenqrusher status
=== tokenQrusher Status ===

Hooks:
  ? token-context   (Filters context)
  ? token-heartbeat (Optimizes heartbeat)

tokenqrusher install [--hooks] [--all]

Installs/enables hooks.

$ tokenqrusher install --hooks
? Enabled: token-context
? Enabled: token-heartbeat

Configuration

All hook configs are JSON files stored in: ~/.openclaw/hooks//config.json

You can edit these to customize behavior (e.g., adjust file lists, intervals, or quiet hours). Changes are reloaded after 60 seconds (config cache TTL).

Design Principles

• Deterministic – Same input → same output.
• Pure functions – No hidden side effects.
• Immutability – Frozen data structures.
• No exceptions for control flow – Uses Result/Either types.
• Thread?safe – RLock protected shared state.
• Exhaustive typing – Full type hints.

Performance

Negligible overhead per agent message.

Troubleshooting

Hook not loading?

# Check status
openclaw hooks list

# Should show "? ready" next to token-context and token-heartbeat

# Enable if missing
openclaw hooks enable token-context
openclaw hooks enable token-heartbeat

# Restart gateway
openclaw gateway restart

Changes not taking effect?

Config cache TTL is 60?seconds. Restart the gateway for immediate effect.

Migration from v2.0.x

v2.1.0 removes non?functional components. If upgrading:

1. Disable and remove old hooks:

   openclaw hooks disable token-model
   openclaw hooks disable token-usage
   openclaw hooks disable token-cron
   rm -rf ~/.openclaw/hooks/token-model
   rm -rf ~/.openclaw/hooks/token-usage
   rm -rf ~/.openclaw/hooks/token-cron
   

2. Update the skill:

   clawhub update tokenQrusher
   

3. Re?install remaining hooks:

   tokenqrusher install --hooks
   

4. Restart gateway:

   openclaw gateway restart
   

Removed commands: tokenqrusher model, budget, usage, optimize. They no longer exist.

License

MIT. See LICENSE file in repository.

Credits

• Design & Implementation: Lieutenant?Qrusher (qsmtco)
• Review: Captain?JAQ (SMTCo)
• Framework: OpenClaw Team

Built with OpenClaw: https://github.com/openclaw/openclaw