ClawFirewall Plugin

ClawFirewall is an OpenClaw plugin for request-side budget and token control before an LLM call is sent.

Why use ClawFirewall?

Without a guard layer:

• Costs can grow unpredictably
• Agents may loop or over-call APIs
• No control over token usage

ClawFirewall ensures every request is validated before execution.

What It Does

• Validates request shape (model, prompt, optional sessionSpentUsd)
• Estimates token usage (with conservative CJK handling)
• Rejects requests that exceed maxTokensPerRequest
• Rejects requests that exceed maxBudgetUsd (session spend + projected request cost)
• Optionally suggests a cheaper fallbackModel when cost can be reduced

Install

openclaw plugins install /path/to/clawfirewall-plugin

For registry publishing, include openclaw.plugin.json in the package root.

Config

{
  "maxBudgetUsd": 5,
  "maxTokensPerRequest": 4000,
  "fallbackModel": "gpt-4o-mini",
  "modelPricingUsdPer1K": {
    "gpt-4o": { "input": 0.0025, "output": 0.01 },
    "claude sonnet 4.6": { "input": 0.003, "output": 0.015 }
  },
  "debug": false
}

• maxBudgetUsd: max projected total spend (USD) per guarded call context.
• maxTokensPerRequest: hard cap for estimated prompt (input) tokens.
• fallbackModel: cheaper model candidate used for optimization suggestions.
• modelPricingUsdPer1K: optional model price overrides（USD per 1K input/output tokens）.
• modelPricingUsdPerToken: optional legacy override（USD per 1 token）.
• debug: enables redacted decision logs.

Input/Output Contract

Input:

{
  "model": "gpt-4o",
  "prompt": "Summarize this text ...",
  "expectedOutputTokens": 256,
  "sessionSpentUsd": 0.03
}

Output (allowed):

{
  "allowed": true,
  "tokens": 123,
  "inputTokens": 123,
  "outputTokens": 256,
  "estimatedCostUsd": 0.000615,
  "sessionSpentUsd": 0.03,
  "totalProjectedUsd": 0.030615,
  "originalModel": "gpt-4o",
  "model": "gpt-4o-mini"
}

Output (blocked):

{
  "allowed": false,
  "reason": "budget_exceeded"
}

Security & Privacy Notes

• This plugin runs locally and does not call external APIs by default.
• Debug logs redact keys/tokens/secrets by key-name pattern.
• Keep debug: false in production unless you need troubleshooting output.

Output Token Estimate

• expectedOutputTokens is optional; if omitted, output tokens default to ceil(inputTokens * 0.5) as a conservative estimate so budget checks do not underestimate cost.