Proactive Trigger Plugin

A local OpenClaw plugin that turns ordinary group or channel messages into structured agent tasks.

It is designed to be generic rather than Feishu-specific: the same rule model can work across group chats on any OpenClaw channel as long as the message arrives through the normal reply_dispatch pipeline.

What it does

• Watches incoming chat messages.
• Applies configurable trigger rules.
• Runs an embedded agent task when a rule matches.
• Optionally suppresses unmatched, unmentioned group messages so the default agent does not reply to every casual message.
• Supports both deterministic matching and semantic routing.

Typical use cases:

• summarize an arXiv paper when someone drops an arXiv link
• digest TODO items from a group discussion
• create a reminder from natural language
• add future custom automations without changing plugin code

Routing model

The plugin uses a two-stage routing model.

1. Deterministic filters

A rule can provide hard constraints in when:

• chatTypes
• channels
• requireMention
• urlKinds
• mustContain
• mustNotContain

If a rule has positive deterministic signals such as urlKinds or mustContain, it can become an exact match.

2. Semantic routing

If exact matching is not enough, the plugin asks an embedded router model to choose the best rule based on:

• message body
• channel and chat type
• mention status
• detected URLs
• each rule's when.intentDescription

Important behavior:

• If exact matches exist, the router only chooses among those exact matches.
• If there are no exact matches, semantic-only rules can still match through the router.
• Casual chat should return null and trigger nothing.

This keeps the system flexible while protecting deterministic rules from being overridden by vague semantic guesses.

Configuration

The plugin config lives under plugins.entries.proactive-trigger-plugin.config in ~/.openclaw/openclaw.json.

Top-level fields

• suppressUnmatchedUnmentionedChats: when true, unmatched group/channel messages without mention are swallowed
• rules: ordered rule list

Rule shape

Each rule has this structure:

{
  "id": "rule-id",
  "enabled": true,
  "when": {
    "chatTypes": ["group", "channel"],
    "channels": ["feishu", "discord"],
    "requireMention": false,
    "intentDescription": "Describe what kind of message should trigger this rule.",
    "urlKinds": ["arxiv"],
    "mustContain": [],
    "mustNotContain": []
  },
  "action": {
    "kind": "embedded_agent",
    "promptTemplate": "Your task prompt with {{body}} and other variables.",
    "model": "openai/gpt-5.4",
    "timeoutMs": 120000,
    "disableMessageTool": true,
    "disableTools": false,
    "toolsAllow": ["web_search"],
    "bootstrapContextMode": "lightweight",
    "allowGatewaySubagentBinding": false,
    "useCurrentSessionContext": false
  }
}

Template variables

The action prompt supports values such as:

• {{body}}
• {{first_url}}
• {{first_arxiv_url}}
• {{all_urls}}
• {{channel}}
• {{chat_type}}
• {{sender_name}}
• {{message_thread_id}}
• {{session_key}}

Recommended rule style

For most new rules, prefer semantic intent description first:

• put the trigger meaning in when.intentDescription
• keep text understanding in when.intentDescription instead of encoding it as a rigid text pattern
• use urlKinds or mustContain only when deterministic filtering is truly useful

Recommended patterns:

• arXiv summary: urlKinds=["arxiv"] plus a short intentDescription
• TODO digest: semantic-only intentDescription
• reminder creation: semantic-only intentDescription plus useCurrentSessionContext=true if reply binding matters

Example rules

arXiv summary

{
  "id": "arxiv-summary",
  "enabled": true,
  "when": {
    "chatTypes": ["group", "channel"],
    "requireMention": false,
    "urlKinds": ["arxiv"],
    "intentDescription": "Trigger when a group message contains an arXiv paper link and does not mention the agent."
  },
  "action": {
    "kind": "embedded_agent",
    "promptTemplate": "Analyze the arXiv paper linked in {{first_arxiv_url}}. Give a concise summary, key contributions, main method, limitations, and practical takeaways for the group.",
    "toolsAllow": ["web_search"],
    "disableMessageTool": true,
    "bootstrapContextMode": "lightweight"
  }
}

TODO digest

{
  "id": "todo-digest",
  "enabled": true,
  "when": {
    "chatTypes": ["group", "channel"],
    "requireMention": false,
    "intentDescription": "Trigger when the message asks to extract action items, organize TODOs, summarize follow-up work, or record pending tasks from the conversation."
  },
  "action": {
    "kind": "embedded_agent",
    "promptTemplate": "Read the message below and turn it into a clean TODO list with owners, deadlines if available, and open questions.\n\nMessage:\n{{body}}",
    "disableMessageTool": true,
    "bootstrapContextMode": "lightweight"
  }
}

reminder creation

{
  "id": "schedule-reminder",
  "enabled": true,
  "when": {
    "chatTypes": ["group", "channel"],
    "requireMention": false,
    "intentDescription": "Trigger when the message asks to create a reminder, schedule a reminder, remind later, or notify at a specific future time."
  },
  "action": {
    "kind": "embedded_agent",
    "promptTemplate": "Create a reminder based on this message: {{body}}",
    "toolsAllow": ["cron"],
    "disableMessageTool": true,
    "bootstrapContextMode": "lightweight",
    "useCurrentSessionContext": true
  }
}

Runtime management

The plugin also supports rule management through chat.

When the plugin is mentioned together with management intent, it can interpret requests such as:

• list current rules
• add a new rule
• update an existing rule
• enable or disable a rule
• delete a rule
• toggle suppressUnmatchedUnmentionedChats

In other words, this plugin can be both:

• a runtime trigger engine
• a lightweight self-managed rule registry

Safety notes

• Semantic routing should be guided by when.intentDescription, not by vague prompt goals alone.
• Use deterministic constraints for high-risk or expensive automations.
• Keep disableMessageTool=true for autonomous background-style tasks unless the rule truly needs to message during execution.
• If a rule may spend money or trigger external effects, constrain it with chatTypes, channels, mention policy, or additional hard gates.

Current direction

This plugin is intended to be a general proactive automation layer for OpenClaw, including but not limited to:

• paper summary
• TODO extraction
• reminder scheduling
• future user-defined workflow triggers

The goal is to let users define trigger behavior in configuration, with minimal or no code changes.