← Back to Plugins
Tools

Reply Gate

whytobe By whytobe 👁 6 views ▲ 0 votes

OpenClaw plugin: decide whether the assistant should reply, using bounded per-conversation context

GitHub

Install

npm install
npm

README

# openclaw-reply-gate

A channel-agnostic OpenClaw plugin that decides whether the assistant should answer
a message at all. Conversation context comes from the conversation's own session
transcript, so the decision sees the last N messages of that room and nothing else.

## What it does

- Hooks `reply_dispatch` before the ordinary model dispatch.
- Reads up to `contextMessages` recent messages (default 6, range 1 to 20) from the
  current conversation's transcript only. Direct messages and other rooms are never read.
- Asks the agent's configured Decision model whether a reply is useful.
- Skips the reply when the answer is "no", when the provider is unavailable, when the
  message is a plain acknowledgment or sticker, or when the input is stale or duplicated.
- Always answers when the message names the assistant, including common misspellings,
  because an explicit call must never be swallowed by a classifier.

Silenced messages are appended back into the room transcript so the conversation record
stays complete and the next decision still has real context.

## Scope

The gate applies to relations enabled in your own config. It does not create a room
allowlist. A room becomes eligible when it is enabled in the channel config
(for example `channels.line.groups.<id>.enabled`), and rooms that still require a
mention never reach a gate decision because the host drops those messages first.

## Requirements

- OpenClaw with the `reply_dispatch` hook and a Decision model configured for the agent
  (`agents.defaults.decisionModel` or a per-agent override).
- Node 22 or newer.

## Install

```sh
openclaw plugins install <packed .tgz or this repository>
```

Then grant conversation access and a hook budget larger than the owned decision deadline:

```json5
{
  plugins: {
    entries: {
      "reply-gate": {
        enabled: true,
        hooks: {
          allowConversationAccess: true,
          timeouts: { reply_dispatch: 6500 }
        }
      }
    }
  }
}
```

## Configuration

All settings are optional and live under `plugins.entries.reply-gate.config`.

| Key | Default | Meaning |
| --- | --- | --- |
| `agentId` | `bugdech` | Agent whose Decision model and transcripts are used. |
| `contextMessages` | `6` | Recent messages from the same conversation sent to the Decision model. Clamped to 1-20. |
| `threshold` | `0.7` | Minimum probability to reply. Clamped to 0.5-0.99. |
| `instructions` | built-in | Replaces the Decision model instruction text. |
| `criteria.true` | built-in | Replaces the "should reply" criteria description. |
| `criteria.false` | built-in | Replaces the "should stay silent" criteria description. |

```json5
{
  plugins: {
    entries: {
      "reply-gate": {
        enabled: true,
        hooks: { allowConversationAccess: true, timeouts: { reply_dispatch: 6500 } },
        config: {
          agentId: "bugdech",
          contextMessages: 6,
          threshold: 0.7,
          instructions: "Decide whether the assistant should answer this family chat message.",
          criteria: {
            true: "The message asks the assistant something or clearly continues its advice.",
            false: "The message is chatter between other people, a sticker, or an acknowledgment."
          }
        }
      }
    }
  }
}
```

## Audit

Every exit path appends one JSON line to `.openclaw/tmp/reply-gate/audit.jsonl` under the
plugin workspace. Records contain the channel, conversation id, reason, whether the reply
was silenced, the probability and model, the message count, and timings. Message text and
sender identities are never recorded.

Reasons: `room_not_enabled`, `slash_command`, `duplicate`, `stale_or_invalid_timestamp`,
`cheap_acknowledgement`, `explicit_mention`, `decision_reply`, `decision_silent`,
`gate_error`.

## Development

```sh
npm install
npm test
```

## Limitations

- A claim hook is not a security boundary. If the hook is skipped, disabled, or loses to
  another claimant, the host falls back to its normal reply behavior and the assistant may
  answer messages the gate would have silenced.
- Decisions are probabilistic. Tune the rubric and threshold against real traffic.
- The transcript reader is read-mostly; the plugin never rewrites conversation content.
tools

Comments

Sign in to leave a comment

Loading comments...