Problem Manifestation

Developers attempting to build ambient awareness systems encounter a fundamental architectural limitation: no visibility into messages that fail channel-level filters.

Scenario 1: Ambient Context Collector

typescript // Intended usage - wanting to observe ALL messages api.on(“message”, async (event) => { // This only fires for messages that pass: // 1. Group membership allowlist // 2. Sender policy (groupPolicy + groupAllowFrom) // 3. Mention/activation gating await contextCollector.addToKnowledgeGraph(event); });

Actual behavior: Messages from non-allowlisted groups, blocked senders, or messages lacking required mentions are silently discarded before reaching any plugin hook.

Scenario 2: WhatsApp Passive Listener

typescript // Want to monitor group conversations without responding api.on(“message”, async (msg) => { await auditLog.record(msg); // Only fires for allowed messages });

Result: The bot sees no messages unless users specifically mention it, defeating the purpose of passive monitoring.

Scenario 3: Cross-Channel Pattern Detection

typescript // Attempting to correlate signals across channels api.on(“message”, async (event) => { if (event.channel === ‘whatsapp’) { await patternAnalyzer.process(event); } });

Limitation: WhatsApp messages require mentions due to requireMention configuration; without mentions, no events fire.

Current Workarounds (Problematic)

• Widen allowlist + requireMention: Mention still triggers response pipeline
• Patch compiled JS: Fragile, breaks on updates, unsupported
• Secondary baileys connection: Conflicts with single-session WhatsApp Web architecture
• Gateway log parsing: Unstructured format, not stable API, high overhead

Error Patterns

# Attempting to access filtered messages
[ChannelRouter] Message from unknown sender blocked: sender=sender_id channel=whatsapp
[ChannelRouter] Chat not in allowlist: chat_id=group_id action=drop

# No hook fires - silent drop
[FilterChain] Skipping message - failed allowlist check
[FilterChain] Skipping message - failed mention gate

Architectural Analysis

The current OpenClaw message processing pipeline applies filters before plugin hooks execute. This creates a hard boundary that prevents observation of rejected messages.

Current Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                        MESSAGE PROCESSING PIPELINE                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  [Transport Layer]                                                      │
│       │                                                                │
│       ▼                                                                │
│  ┌─────────────┐                                                       │
│  │ Raw Message │  ← on_raw_inbound SHOULD fire here                    │
│  └─────────────┘                                                       │
│       │                                                                │
│       ▼                                                                │
│  ┌─────────────────────────────────────────┐                           │
│  │         FILTER CHAIN                    │                           │
│  │  ┌─────────────────────────────────┐    │                           │
│  │  │ 1. Allowlist Check              │    │                           │
│  │  │ 2. Sender Policy Check          │    │                           │
│  │  │ 3. Mention Gating               │    │                           │
│  │  └─────────────────────────────────┘    │                           │
│  └─────────────────────────────────────────┘                           │
│       │                    │                                            │
│       ▼ (pass)             ▼ (fail/drop)                                │
│  ┌─────────────┐      ┌─────────────────┐                               │
│  │ Plugin Hooks│      │ Message Dropped │                               │
│  │ (on_message)│      │ No Hooks Fire   │                               │
│  └─────────────┘      └─────────────────┘                               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Filter Chain Implementation

The filtering occurs in the channel router at the transport abstraction layer:

typescript // Current architecture (simplified) class ChannelRouter { async routeMessage(rawMessage: RawMessage): Promise { // 1. Parse raw message const parsed = this.parseMessage(rawMessage);

// 2. APPLY FILTERS BEFORE HOOKS
if (!this.checkAllowlist(parsed.chatId)) {
  return; // Message dropped - no hook fires
}

if (!this.checkSenderPolicy(parsed.senderId)) {
  return; // Message dropped - no hook fires
}

if (!this.checkMentionGating(parsed)) {
  return; // Message dropped - no hook fires
}

// 3. Only now do hooks fire
await this.emitToPlugins(parsed);

} }

Why This Design Exists

1. Performance: Rejecting messages early avoids expensive plugin processing
2. Security: Prevents information leakage from unauthorized sources
3. Simplicity: Plugins only see "actionable" messages

Architectural Gap

The disconnect occurs because:

• Plugin hooks are treated as part of the agent pipeline
• Channel filters operate at the transport layer (below plugin abstraction)
• No observation path exists between raw message receipt and filter application

Technology-Specific Constraints

WhatsApp (Baileys): typescript // Baileys emits messages → OpenClaw receives → filters applied → hooks fire // No interception point for observing before filters

Telegram: typescript // Bot API → Update received → filters → hooks // Webhook/polling mechanism provides no pre-filter access

Discord: typescript // Gateway event → OpenClaw handler → filters → hooks // Discord’s gateway protocol has no pre-filter event system

Implementation Strategy

Add a new plugin hook on_raw_inbound that fires immediately after raw message parsing but before any filter chain application.

Phase 1: Core Hook Registration

File: packages/core/src/plugins/hook-registry.ts

typescript // Add new hook type export enum PluginHookType { // … existing hooks ON_MESSAGE = ‘on_message’, ON_RAW_INBOUND = ‘on_raw_inbound’, // NEW BEFORE_PROMPT_BUILD = ‘before_prompt_build’, // … }

// Update hook registration export interface RawInboundEvent { readonly channel: string; readonly chatId: string; readonly senderId: string; readonly senderName?: string; readonly text?: string; readonly timestamp: number; readonly raw: Record<string, unknown>; // Channel-specific raw payload readonly metadata: { groupName?: string; isGroup: boolean; mentions?: string[]; rawSource: ’telegram’ | ‘whatsapp’ | ‘discord’ | ‘signal’ | ‘webhook’; }; }

Phase 2: Channel Router Modification

File: packages/channels/src/channel-router.ts

typescript class ChannelRouter { async routeMessage(rawMessage: RawMessage): Promise { // 1. Parse raw message const parsed = this.parseMessage(rawMessage);

// 2. FIRE on_raw_inbound HOOK (NEW)
await this.emitRawInbound(parsed);

// 3. Continue with existing filter chain
if (!this.checkAllowlist(parsed.chatId)) {
  this.logger.debug('Message dropped: allowlist check failed', {
    chatId: parsed.chatId
  });
  return;
}

if (!this.checkSenderPolicy(parsed.senderId)) {
  this.logger.debug('Message dropped: sender policy check failed', {
    senderId: parsed.senderId
  });
  return;
}

if (!this.checkMentionGating(parsed)) {
  this.logger.debug('Message dropped: mention gating failed', {
    chatId: parsed.chatId
  });
  return;
}

// 4. Existing hook emission
await this.emitToPlugins(parsed);

}

// NEW: Raw inbound emission private async emitRawInbound(event: RawInboundEvent): Promise { const hooks = this.pluginManager.getHooks(PluginHookType.ON_RAW_INBOUND);

for (const hook of hooks) {
  try {
    await hook.handler(event);
  } catch (error) {
    this.logger.error('on_raw_inbound hook failed', {
      hook: hook.name,
      error: error.message
    });
    // Never propagate - observation hooks must not break processing
  }
}

} }

Phase 3: Plugin API Update

File: packages/core/src/plugins/plugin-api.ts

typescript export class PluginApi { // … existing methods

/**

• Register handler for raw inbound messages.
• Fires BEFORE channel filtering (allowlist, sender policy, mention gating).
• Return value is ignored - this is observe-only.
• @param handler - Async function to handle raw messages */ onRawInbound( handler: (event: RawInboundEvent) => Promise ): void { this.registerHook({ type: PluginHookType.ON_RAW_INBOUND, handler, name: handler.name || ‘anonymous_on_raw_inbound’ }); }

// Alternative: Event emitter style on(event: ‘on_raw_inbound’, handler: (event: RawInboundEvent) => Promise): void; }

Phase 4: TypeScript Type Definitions

File: packages/types/src/plugin-events.ts

typescript export interface RawInboundEvent { /** Source channel (telegram, whatsapp, discord, signal) */ channel: ChannelType;

/** Unique chat/group identifier */ chatId: string;

/** Message sender’s unique identifier */ senderId: string;

/** Display name of sender if available */ senderName?: string;

/** Message text content (if text-based channel) */ text?: string;

/** Unix timestamp of message receipt */ timestamp: number;

/** Channel-specific raw payload for advanced processing */ raw: ChannelRawPayload;

/** Additional message metadata */ metadata: RawInboundMetadata; }

export interface RawInboundMetadata { /** Whether message originated from a group/channel */ isGroup: boolean;

/** Group display name (if group) */ groupName?: string;

/** User IDs mentioned in message */ mentions?: string[];

/** Transport source */ rawSource: ’telegram’ | ‘whatsapp’ | ‘discord’ | ‘signal’ | ‘webhook’; }

Configuration Integration

File: packages/config/src/channel-config.ts

typescript export interface ChannelGroupConfig { /** Enable raw inbound observation for this group */ observe?: boolean;

/** Sink for observed messages when observe is enabled */ observeSink?: ‘hook’ | ‘jsonl’ | ‘webhook’;

/** Webhook URL for observeSink: ‘webhook’ */ observeWebhookUrl?: string;

/** JSONL file path for observeSink: ‘jsonl’ */ observeJsonlPath?: string; }

Usage Example

typescript // Plugin: ambient-context-collector export default { name: ‘ambient-context-collector’, version: ‘1.0.0’,

async onLoad(api: PluginApi): Promise { // Register raw inbound handler api.onRawInbound(async (event) => { // This fires for EVERY message before filtering await this.processAmbientEvent(event); }); },

async processAmbientEvent(event: RawInboundEvent): Promise { // Build knowledge graph from all observed messages await this.graph.addNode({ type: ‘observed_message’, channel: event.channel, chatId: event.chatId, senderId: event.senderId, timestamp: event.timestamp, content: event.text });

// Track conversation patterns
await this.patternTracker.record({
  chatId: event.chatId,
  sender: event.senderName,
  activity: 'message_sent'
});

} };

Configuration Example

yaml

openclaw.yaml

channels: whatsapp: groups: - id: “family-group-123” allowFrom: ["+1234567890"] requireMention: true # NEW: Enable raw observation without response observe: true observeSink: jsonl observeJsonlPath: “./logs/family-ambient.jsonl”

  - id: "work-team-456"
    allowFrom: ["+0987654321"]
    observe: true
    observeSink: webhook
    observeWebhookUrl: "https://analytics.internal/events"

Implementation Pitfalls

1. Blocking Hook Execution

   typescript // BAD: Synchronous blocking in handler api.onRawInbound(async (event) => { await fs.promises.writeFile(’/tmp/all-messages.log’, JSON.stringify(event)); // fs.writeFile is synchronous - blocks processing });

   // GOOD: Non-blocking api.onRawInbound(async (event) => { writeToLogQueue(event); // Queue-based, non-blocking });

2. Memory Leaks from Unbounded State**

   typescript // BAD: Accumulating all messages const allMessages: RawInboundEvent[] = [];

   api.onRawInbound(async (event) => { allMessages.push(event); // Unbounded growth });

   // GOOD: Sliding window or sampling const recentMessages = new CircularBuffer(1000); api.onRawInbound(async (event) => { recentMessages.push(event); });

3. Assuming Hook Fires for All Messages**

   The hook fires at the channel router level. Edge cases:

   • Malformed messages that fail parsing (hook does NOT fire)
   • System messages (join/leave) may have different behavior per channel
   • Messages received during connection loss may be batch-processed differently
4. Overwriting Plugin State**

   typescript // BAD: Shared mutable state across handler invocations let lastProcessedChat: string;

   api.onRawInbound(async (event) => { lastProcessedChat = event.chatId; // Race condition await processChat(event.chatId); });

Configuration Pitfalls

• observe: true without sink: Messages logged but no output destination configured
• Webhook timeout: Long-running webhooks block subsequent hook executions
• JSONL file rotation: Without logrotate, files grow indefinitely
• Permission errors: JSONL path directory may not exist or be writable

Environment-Specific Concerns

Docker:

# Volume mount JSONL paths correctly
volumes:
  - ./logs:/app/logs  # Ensure directory exists before container start

# Webhook connectivity from inside container
# Use host.docker.internal or Docker network aliases

macOS:

# File watching may behave differently
# Test JSONL writes on macOS NFS mounts
# Path separator differences (though Node handles this)

Windows:

# Path handling: Use path.join() for cross-platform
# Line endings in JSONL: Always use \n (LF), not \r\n
# Permission issues: Run container as non-root if possible

Performance Considerations

Related Feature Requests

• #247: Channel-level message mirroring
  Similar need for observing messages without response, proposes webhook-based mirroring
• #189: Mention gating bypass for specific roles
  Related to filtering before mention check, different use case but same architectural constraint
• #312: Per-group response policies
  Proposes granular control over which messages trigger agent pipeline
• #156: WhatsApp passive mode
  Direct WhatsApp-specific request for observing without responding

Historical Issues

• Message silently dropped with no logging
  Users confused by messages not appearing - was due to filter chain, not bugs
• on_message not firing for Telegram groups
  Root cause: Missing bot mention in groups requires specific configuration
• WhatsApp multi-device conflicts
  Secondary baileys connections conflict with primary session - prevents workaround

Complementary Features

Architecture Links

• Channel Router: `packages/channels/src/channel-router.ts` - Filter chain implementation
• Plugin Manager: `packages/core/src/plugins/plugin-manager.ts` - Hook registry
• Hook Types: `packages/types/src/plugin-events.ts` - Event type definitions
• Baileys Integration: `packages/channels/whatsapp/src/baileys-adapter.ts` - WhatsApp transport

External References

• Baileys library: WhiskeySockets/Baileys - Single session constraint
• Telegram Bot API: Message filtering - Groups vs channels
• Discord Gateway: Intent system - Message content access