OpenClaw Tool Pre-filter (openclaw-tool-prefilter)

September 20, 2026 · View on GitHub

Dynamic two-stage skill and tool pre-filtering plugin for OpenClaw, powered by Decision Models (such as Jev / TypeSafe).

🎯 The Problem

By default, an AI agent loads dozens of tool schemas and skill definitions on every single turn. This causes:

Excess Context Bloat: 5,000–10,000+ tokens consumed per turn just for tool schemas.
Higher Costs & Latency: Slower time-to-first-token (TTFT) and unnecessary API expenses.
Tool Hallucinations: Conversational queries ("Hello", "Explain how quicksort works") risk triggering unrelated tools accidentally.

💡 The Solution

openclaw-tool-prefilter hooks into the agent runtime at before_prompt_build:

User Turn
   │
   ▼
[Decision Model: Jev / TypeSafe]  ── (Fast, ~40ms, <\$0.0001)
   │
   ├─ Probability < threshold (e.g. Pure Chat) ──► Prune tool schemas (`toolsAllow: []`)
   │                                                ⚡ Saves 5,000-10,000 tokens!
   │
   └─ Probability >= threshold (Action Needed) ──► Pass-through tools unconstrained

Pure Conversation Optimization: Strips tool definitions when no actions are needed, saving thousands of tokens.
Zero Hallucination: Eliminates unwanted tool calls on casual chit-chat, explanations, or code reviews.
Bulletproof Fail-Open Safety: If the decision provider experiences network issues, rate limits, or timeouts, the plugin immediately fails open (no restrictions). Agent dialogue is never blocked.
Compliant Request Boundaries: Correctly respects empty message inputs (e.g., image-only messages) without polluting context from historical prompt strings.

📦 Installation

From ClawHub (Recommended)

openclaw plugins install clawhub:openclaw-tool-prefilter

From npm

openclaw plugins install npm:openclaw-tool-prefilter

From Local Source

git clone https://github.com/MertBasar0/openclaw-tool-prefilter.git
openclaw plugins install ./openclaw-tool-prefilter

⚙️ Configuration

In your openclaw.json or agent configuration:

{
  "plugins": {
    "tool-prefilter": {
      "enabled": true,
      "thresholdAnyTool": 0.35,
      "timeoutMs": 500
    }
  }
}

Options

Parameter	Type	Default	Description
`enabled`	`boolean`	`true`	Enable or disable pre-filtering.
`thresholdAnyTool`	`number`	`0.35`	Probability threshold. Turns below this are treated as pure conversation.
`timeoutMs`	`number`	`500`	Hard timeout for decision evaluation before failing open.

📊 Token Savings Benchmark

Scenario	Raw Context	With Tool Pre-filter	Savings
"Nasılsın? Bugün hava nasıl?"	~8,400 tokens	~420 tokens	95.0%
"Explain how raft consensus works"	~9,200 tokens	~580 tokens	93.7%
"Git status kontrol et ve commit at"	~8,900 tokens	~8,900 tokens	Pass-through

🧪 Testing & Verification

Run the automated test suite:

npm test

Build the distribution bundle:

npm run build