Guard (OpenClaw plugin)

Guard is a gate in front of every LLM call: it validates the request, estimates tokens (with conservative CJK handling), enforces session budget and per-request token caps, and can suggest a cheaper fallback model when policy allows. It runs locally and does not call external APIs by default.

Install

openclaw plugins install /path/to/guard

Publish to a registry with openclaw.plugin.json at 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) the guard permits for this call (session spend plus this request).
• maxTokensPerRequest: hard cap on estimated input tokens.
• fallbackModel: cheaper model the guard may return when a downgrade is allowed.
• modelPricingUsdPer1K: optional per-model pricing for guard estimates (USD per 1K input/output tokens).
• modelPricingUsdPerToken: optional legacy override (USD per token, same for input and output).
• debug: enables redacted decision logs.

Input / output

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"
}

Output token estimate

If expectedOutputTokens is omitted, output tokens default to ceil(inputTokens * 0.5) so the guard does not underestimate cost.

Privacy

This plugin runs in-process. Debug logs redact keys, tokens, and secrets by key-name pattern; keep debug off in production unless you are troubleshooting.