openclaw-triage-gate 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# openclaw-triage-gate
+
+A lightweight triage gate for OpenClaw group chats. Uses a cheap model to decide if the bot should respond before the expensive main model runs.
+
+## The Problem
+
+When an OpenClaw bot is in group chats with `requireMention: false`, **every message** triggers the main model (e.g. Opus at $15/M input, $75/M output) — even when the bot decides not to respond (`NO_REPLY`). In active groups, this wastes most of the token budget on messages the bot ignores anyway.
+
+## The Solution
+
+This plugin intercepts group messages **before** the main model runs. It calls a cheap triage model (e.g. Haiku at $1/M input, $5/M output) to make a quick RESPOND/SKIP decision. If the triage model says SKIP, the main model never fires.
+
+```
+Group message → Triage model (cheap) → SKIP? → Done ($0.001)
+                                      → RESPOND? → Main model (expensive) → Reply
+```
+
+DMs always pass through without triage.
+
+## Estimated Savings
+
+Assuming ~80% of group messages don't need a response:
+
+| Scenario | Cost per 100 messages |
+|----------|----------------------|
+| Without plugin (all Opus) | $5-22 |
+| With plugin (Haiku triage) | $1-5 |
+
+**75-90% reduction in group chat token costs.**
+
+## Install
+
+```bash
+openclaw plugins install openclaw-triage-gate
+```
+
+## Configure
+
+Add to your OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "triage-gate": {
+        "enabled": true,
+        "config": {
+          "triageModel": "anthropic/claude-haiku-4-5-20251001"
+        }
+      }
+    }
+  }
+}
+```
+
+Or via CLI:
+
+```bash
+openclaw config set plugins.entries.triage-gate.enabled true
+openclaw config set plugins.entries.triage-gate.config.triageModel "anthropic/claude-haiku-4-5-20251001"
+```
+
+## Config Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `triageModel` | string | `anthropic/claude-haiku-4-5-20251001` | Model for triage decisions, in `provider/model` format |
+| `triagePrompt` | string | (built-in) | Custom prompt — must instruct the model to reply RESPOND or SKIP |
+| `groups` | string[] | all groups | Only apply triage to these group IDs |
+| `excludeGroups` | string[] | none | Skip triage for these group IDs |
+| `maxTriageTokens` | number | 10 | Max output tokens for triage response |
+| `logDecisions` | boolean | true | Log each triage decision |
+
+### Model Examples
+
+Use any model your OpenClaw instance has configured:
+
+```json
+{ "triageModel": "anthropic/claude-haiku-4-5-20251001" }
+{ "triageModel": "minimax/minimax-m2.5" }
+{ "triageModel": "openai/gpt-4.1-mini" }
+{ "triageModel": "openrouter/meta-llama/llama-4-scout" }
+```
+
+The plugin resolves API keys from OpenClaw's existing provider config — no need to add API keys to the plugin config.
+
+### Custom Triage Prompt
+
+You can customize when the bot responds by providing your own prompt:
+
+```json
+{
+  "triagePrompt": "You are a triage system. Reply RESPOND if the message needs the bot's attention, SKIP otherwise.\n\nAlways RESPOND to: questions, requests for help, mentions of health or emergencies.\nAlways SKIP: greetings, emoji reactions, casual chat."
+}
+```
+
+## How It Works
+
+1. The plugin registers a `before_dispatch` hook in OpenClaw
+2. When a group message arrives, the hook fires before the main agent
+3. The plugin calls the configured triage model with the message content
+4. If the model says SKIP, the plugin returns `{ handled: true }` — the main agent never runs
+5. If the model says RESPOND (or anything unclear), the message proceeds to the main agent normally
+
+On any error (API timeout, missing key, etc.), the plugin defaults to letting the message through. Better to waste some tokens than silently drop messages.
+
+## Future Enhancements
+
+These are planned but not yet implemented:
+
+- Recent message history in triage context for better accuracy
+- Per-group custom triage prompts
+- Confidence scores with configurable thresholds
+- Analytics dashboard (hit/miss ratio, tokens saved)
+- Keyword bypass list (always respond to certain words)
+- Rate-based bypass (skip triage in quiet groups)
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,63 @@
+{
+  "id": "triage-gate",
+  "name": "Triage Gate",
+  "description": "Uses a cheap model to decide if the bot should respond in group chats before the main model runs. Saves 75-90% of group chat token costs.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "triageModel": {
+        "type": "string",
+        "description": "Model to use for triage decisions, in provider/model format."
+      },
+      "triagePrompt": {
+        "type": "string",
+        "description": "Custom prompt for triage decisions. Must instruct the model to reply with RESPOND or SKIP."
+      },
+      "groups": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Only apply triage to these group IDs. Empty means all groups."
+      },
+      "excludeGroups": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Skip triage for these group IDs (always let messages through)."
+      },
+      "maxTriageTokens": {
+        "type": "number",
+        "description": "Max output tokens for the triage model response."
+      },
+      "logDecisions": {
+        "type": "boolean",
+        "description": "Whether to log each triage decision."
+      }
+    }
+  },
+  "uiHints": {
+    "triageModel": {
+      "label": "Triage Model",
+      "help": "Model for triage decisions (e.g. anthropic/claude-haiku-4-5, minimax/minimax-m2.5). Default: anthropic/claude-haiku-4-5-20251001"
+    },
+    "triagePrompt": {
+      "label": "Triage Prompt",
+      "help": "Custom prompt that tells the triage model when to RESPOND vs SKIP"
+    },
+    "groups": {
+      "label": "Groups",
+      "help": "Group IDs to apply triage to (empty = all groups)"
+    },
+    "excludeGroups": {
+      "label": "Exclude Groups",
+      "help": "Group IDs to skip triage for (messages always proceed to main model)"
+    },
+    "maxTriageTokens": {
+      "label": "Max Triage Tokens",
+      "help": "Max output tokens for triage response (default: 10)"
+    },
+    "logDecisions": {
+      "label": "Log Decisions",
+      "help": "Log each triage decision to the plugin logger (default: true)"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "openclaw-triage-gate",
+  "version": "1.0.0",
+  "description": "A lightweight triage gate for OpenClaw group chats. Uses a cheap model to decide if the bot should respond before the expensive main model runs.",
+  "type": "module",
+  "main": "src/index.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/as3445/openclaw-triage-gate.git"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "triage",
+    "token-optimization",
+    "group-chat"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.3.22"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "install": {
+      "npmSpec": "openclaw-triage-gate"
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,82 @@
+/**
+ * Configuration for the triage-gate plugin.
+ *
+ * All fields are optional — sensible defaults are used when omitted.
+ */
+export type TriageGateConfig = {
+  /**
+   * Model to use for triage decisions, in "provider/model" format.
+   *
+   * Examples:
+   *   "anthropic/claude-haiku-4-5-20251001"
+   *   "minimax/minimax-m2.5"
+   *   "openai/gpt-4.1-mini"
+   *
+   * The plugin resolves the API key from OpenClaw's configured providers —
+   * no need to put API keys in the plugin config.
+   *
+   * Default: "anthropic/claude-haiku-4-5-20251001"
+   */
+  triageModel?: string;
+
+  /**
+   * Custom prompt for triage decisions. Replaces the built-in default.
+   * Must instruct the model to reply with exactly "RESPOND" or "SKIP".
+   *
+   * The message content is appended after this prompt.
+   */
+  triagePrompt?: string;
+
+  /**
+   * Only apply triage to these group IDs. When empty or omitted,
+   * triage applies to ALL group chats.
+   */
+  groups?: string[];
+
+  /**
+   * Skip triage for these group IDs — messages in these groups
+   * always proceed to the main model.
+   */
+  excludeGroups?: string[];
+
+  /**
+   * Max output tokens for the triage model response.
+   * Keep this low — we only need "RESPOND" or "SKIP".
+   * Default: 10
+   */
+  maxTriageTokens?: number;
+
+  /**
+   * Whether to log each triage decision.
+   * Default: true
+   */
+  logDecisions?: boolean;
+};
+
+/** The default triage model when none is configured. */
+export const DEFAULT_TRIAGE_MODEL = "anthropic/claude-haiku-4-5-20251001";
+
+/** The default max output tokens for a triage call. */
+export const DEFAULT_MAX_TRIAGE_TOKENS = 10;
+
+/**
+ * The built-in triage prompt. Instructs the model to reply with
+ * exactly "RESPOND" or "SKIP" based on whether the bot should reply.
+ */
+export const DEFAULT_TRIAGE_PROMPT = `You are a message triage system for a group chat bot.
+Decide if the bot should respond to this message.
+
+Reply ONLY with "RESPOND" or "SKIP". Nothing else.
+
+RESPOND when:
+- The bot is directly addressed by name or asked a question
+- The bot can add genuine value (information, help, insight)
+- Something urgent or important is happening
+- Correcting significant misinformation
+
+SKIP when:
+- Casual banter between people
+- Someone already answered the question
+- A response would just be acknowledgment ("nice", "yeah", "lol")
+- The conversation is flowing fine without the bot
+- The message is a reaction, emoji, or sticker`;

package/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * openclaw-triage-gate — A lightweight triage gate for OpenClaw group chats.
+ *
+ * Registers a `before_dispatch` hook that intercepts group chat messages.
+ * For each group message, it calls a cheap model (e.g. Haiku) to decide
+ * whether the bot should respond. If the triage model says "SKIP", the
+ * main model (e.g. Opus) never runs — saving tokens and money.
+ *
+ * DMs always pass through without triage.
+ */
+
+import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import { evaluateMessage } from "./triage.js";
+import { type TriageGateConfig } from "./config.js";
+
+export default definePluginEntry({
+  id: "triage-gate",
+  name: "Triage Gate",
+  description:
+    "Uses a cheap model to decide if the bot should respond in group chats, saving 75-90% of group chat token costs.",
+
+  register(api: OpenClawPluginApi) {
+    const config = (api.pluginConfig ?? {}) as TriageGateConfig;
+    const logDecisions = config.logDecisions !== false; // default: true
+
+    // Pre-compute the set of groups to include/exclude for fast lookups
+    const includeGroups = config.groups?.length
+      ? new Set(config.groups)
+      : null; // null = all groups
+    const excludeGroups = config.excludeGroups?.length
+      ? new Set(config.excludeGroups)
+      : null;
+
+    /**
+     * Resolve an API key for a provider/model using OpenClaw's auth system.
+     * This keeps the plugin model-agnostic — it works with any provider
+     * the user has configured in OpenClaw.
+     */
+    async function resolveApiKey(provider: string, _model: string): Promise<string> {
+      try {
+        const result = await api.runtime.modelAuth.resolveApiKeyForProvider({
+          provider,
+        });
+        return result?.apiKey ?? "";
+      } catch {
+        return "";
+      }
+    }
+
+    // Register the before_dispatch hook. This fires for every inbound message
+    // BEFORE the main agent (Opus, Sonnet, etc.) processes it.
+    api.on("before_dispatch", async (event) => {
+      // Only triage group messages — DMs always go through
+      if (!event.isGroup) {
+        return; // undefined = no decision, proceed normally
+      }
+
+      // Check if this group should be triaged
+      const groupId = event.sessionKey ?? "";
+      if (excludeGroups?.has(groupId)) {
+        return; // This group is excluded from triage
+      }
+      if (includeGroups && !includeGroups.has(groupId)) {
+        return; // This group isn't in the include list
+      }
+
+      // Skip triage for very short messages (likely reactions or stickers)
+      if (!event.content || event.content.trim().length < 2) {
+        return { handled: true }; // Skip silently
+      }
+
+      // Run the triage model
+      const result = await evaluateMessage({
+        content: event.content,
+        config,
+        resolveApiKey,
+        logger: logDecisions ? api.logger : undefined,
+      });
+
+      if (logDecisions) {
+        const decision = result.shouldRespond ? "RESPOND" : "SKIP";
+        api.logger.info?.(
+          `triage-gate: ${decision} (${result.durationMs}ms) — "${event.content.slice(0, 80)}"`,
+        );
+      }
+
+      if (!result.shouldRespond) {
+        // Tell OpenClaw to skip the main agent for this message
+        return { handled: true };
+      }
+
+      // Let the message through to the main agent
+      return; // undefined = proceed normally
+    });
+
+    api.logger.info?.("triage-gate: plugin loaded");
+  },
+});

package/src/providers.ts

@@ -0,0 +1,149 @@
+/**
+ * Thin adapter that maps a provider name to its API endpoint and request format.
+ *
+ * Supports two API formats:
+ *   1. Anthropic Messages API (for Anthropic models)
+ *   2. OpenAI-compatible Chat Completions API (for everything else)
+ *
+ * Future: add more provider-specific formats here as needed.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ProviderAdapter = {
+  /** Full URL to POST the request to. */
+  endpoint: string;
+
+  /** Build the fetch request body for this provider. */
+  buildRequestBody: (params: {
+    model: string;
+    systemPrompt: string;
+    userMessage: string;
+    maxTokens: number;
+  }) => string;
+
+  /** Build the request headers (including auth). */
+  buildHeaders: (apiKey: string) => Record<string, string>;
+
+  /** Extract the text response from the API response body. */
+  extractResponse: (body: unknown) => string;
+};
+
+// ---------------------------------------------------------------------------
+// Anthropic Messages API
+// ---------------------------------------------------------------------------
+
+const anthropicAdapter: ProviderAdapter = {
+  endpoint: "https://api.anthropic.com/v1/messages",
+
+  buildRequestBody({ model, systemPrompt, userMessage, maxTokens }) {
+    return JSON.stringify({
+      model,
+      max_tokens: maxTokens,
+      system: systemPrompt,
+      messages: [{ role: "user", content: userMessage }],
+    });
+  },
+
+  buildHeaders(apiKey) {
+    return {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    };
+  },
+
+  extractResponse(body) {
+    const msg = body as { content?: Array<{ type: string; text?: string }> };
+    const textBlock = msg.content?.find((b) => b.type === "text");
+    return textBlock?.text?.trim() ?? "";
+  },
+};
+
+// ---------------------------------------------------------------------------
+// OpenAI-compatible Chat Completions API
+// Used for OpenAI, OpenRouter, MiniMax, and other compatible providers.
+// ---------------------------------------------------------------------------
+
+/**
+ * Known base URLs for providers that use the OpenAI-compatible format.
+ * If a provider isn't listed here, we fall back to OpenAI's endpoint.
+ */
+const OPENAI_COMPATIBLE_ENDPOINTS: Record<string, string> = {
+  openai: "https://api.openai.com/v1/chat/completions",
+  openrouter: "https://openrouter.ai/api/v1/chat/completions",
+  minimax: "https://openrouter.ai/api/v1/chat/completions",
+};
+
+function createOpenAICompatibleAdapter(provider: string): ProviderAdapter {
+  const endpoint =
+    OPENAI_COMPATIBLE_ENDPOINTS[provider] ??
+    "https://api.openai.com/v1/chat/completions";
+
+  return {
+    endpoint,
+
+    buildRequestBody({ model, systemPrompt, userMessage, maxTokens }) {
+      return JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userMessage },
+        ],
+      });
+    },
+
+    buildHeaders(apiKey) {
+      return {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      };
+    },
+
+    extractResponse(body) {
+      const resp = body as {
+        choices?: Array<{ message?: { content?: string } }>;
+      };
+      return resp.choices?.[0]?.message?.content?.trim() ?? "";
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a "provider/model" string into its two parts.
+ *
+ * Examples:
+ *   "anthropic/claude-haiku-4-5-20251001" → { provider: "anthropic", model: "claude-haiku-4-5-20251001" }
+ *   "openai/gpt-4.1-mini" → { provider: "openai", model: "gpt-4.1-mini" }
+ *   "minimax/minimax/minimax-m2.5" → { provider: "minimax", model: "minimax/minimax-m2.5" }
+ */
+export function parseModelString(modelString: string): {
+  provider: string;
+  model: string;
+} {
+  const slashIndex = modelString.indexOf("/");
+  if (slashIndex === -1) {
+    return { provider: "anthropic", model: modelString };
+  }
+  return {
+    provider: modelString.slice(0, slashIndex),
+    model: modelString.slice(slashIndex + 1),
+  };
+}
+
+/**
+ * Get the appropriate API adapter for a given provider.
+ */
+export function getProviderAdapter(provider: string): ProviderAdapter {
+  if (provider === "anthropic") {
+    return anthropicAdapter;
+  }
+  return createOpenAICompatibleAdapter(provider);
+}

package/src/triage.ts

@@ -0,0 +1,142 @@
+/**
+ * Core triage logic: calls a cheap model to decide if the bot should respond.
+ *
+ * The flow is simple:
+ *   1. Build a prompt with the triage instructions + the message content
+ *   2. Call the triage model via its provider's API
+ *   3. Parse the response as RESPOND or SKIP
+ *   4. Return true (should respond) or false (skip)
+ */
+
+import {
+  DEFAULT_TRIAGE_MODEL,
+  DEFAULT_TRIAGE_PROMPT,
+  DEFAULT_MAX_TRIAGE_TOKENS,
+  type TriageGateConfig,
+} from "./config.js";
+import { parseModelString, getProviderAdapter } from "./providers.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type TriageParams = {
+  /** The message content to evaluate. */
+  content: string;
+
+  /** Plugin config. */
+  config: TriageGateConfig;
+
+  /**
+   * Resolves an API key for a given provider/model.
+   * Injected from the OpenClaw plugin runtime so the plugin stays model-agnostic.
+   */
+  resolveApiKey: (provider: string, model: string) => Promise<string>;
+
+  /** Optional logger for debug output. */
+  logger?: {
+    info?: (msg: string) => void;
+    warn?: (msg: string) => void;
+  };
+};
+
+export type TriageResult = {
+  /** Whether the bot should respond to this message. */
+  shouldRespond: boolean;
+
+  /** The raw response from the triage model (for debugging). */
+  rawResponse: string;
+
+  /** How long the triage call took in milliseconds. */
+  durationMs: number;
+};
+
+// ---------------------------------------------------------------------------
+// Main function
+// ---------------------------------------------------------------------------
+
+/**
+ * Ask a cheap model whether the bot should respond to a group chat message.
+ *
+ * Returns `shouldRespond: true` if the model says RESPOND,
+ * `shouldRespond: false` if it says SKIP.
+ *
+ * On error (API failure, timeout, etc.), defaults to `shouldRespond: true`
+ * so the main model still runs — we'd rather waste some tokens than
+ * silently drop messages.
+ */
+export async function evaluateMessage(params: TriageParams): Promise<TriageResult> {
+  const { content, config, resolveApiKey, logger } = params;
+  const startTime = Date.now();
+
+  const modelString = config.triageModel ?? DEFAULT_TRIAGE_MODEL;
+  const { provider, model } = parseModelString(modelString);
+  const prompt = config.triagePrompt ?? DEFAULT_TRIAGE_PROMPT;
+  const maxTokens = config.maxTriageTokens ?? DEFAULT_MAX_TRIAGE_TOKENS;
+
+  try {
+    // Resolve the API key from OpenClaw's provider config
+    const apiKey = await resolveApiKey(provider, model);
+    if (!apiKey) {
+      logger?.warn?.(`triage-gate: no API key found for provider "${provider}", allowing message through`);
+      return { shouldRespond: true, rawResponse: "", durationMs: Date.now() - startTime };
+    }
+
+    // Get the right adapter for this provider's API format
+    const adapter = getProviderAdapter(provider);
+
+    // Make the API call
+    const response = await fetch(adapter.endpoint, {
+      method: "POST",
+      headers: adapter.buildHeaders(apiKey),
+      body: adapter.buildRequestBody({
+        model,
+        systemPrompt: prompt,
+        userMessage: `Message: ${content}`,
+        maxTokens,
+      }),
+      signal: AbortSignal.timeout(5000), // 5s timeout — triage should be fast
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "unknown error");
+      logger?.warn?.(
+        `triage-gate: API returned ${response.status} from ${provider}, allowing message through. Error: ${errorText}`,
+      );
+      return { shouldRespond: true, rawResponse: errorText, durationMs: Date.now() - startTime };
+    }
+
+    const body = await response.json();
+    const rawResponse = adapter.extractResponse(body);
+    const shouldRespond = parseTriageDecision(rawResponse);
+
+    return { shouldRespond, rawResponse, durationMs: Date.now() - startTime };
+  } catch (error) {
+    // On any error, default to letting the message through.
+    // Better to waste tokens than silently drop a message.
+    logger?.warn?.(`triage-gate: error during triage (${String(error)}), allowing message through`);
+    return { shouldRespond: true, rawResponse: "", durationMs: Date.now() - startTime };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the triage model's response into a boolean decision.
+ *
+ * Looks for "RESPOND" or "SKIP" in the response text.
+ * If unclear, defaults to true (respond) to avoid dropping messages.
+ */
+export function parseTriageDecision(response: string): boolean {
+  const normalized = response.toUpperCase().trim();
+
+  if (normalized.startsWith("SKIP")) return false;
+  if (normalized.startsWith("RESPOND")) return true;
+
+  // If the response doesn't clearly match either, default to responding.
+  // This is intentional — false negatives (bot stays silent when it shouldn't)
+  // are worse than false positives (bot responds when it didn't need to).
+  return true;
+}