Primary Manifestation

When a user sends a message on Telegram during an active heartbeat run in steer queue mode, the user receives no response despite the agent generating a correct reply.

Exact Reproduction Sequence

1. Configure queue mode as steer:

   # config.yaml
   messages:
     queue:
       mode: "steer"
   heartbeat:
     interval: 3s
   

2. Wait for a heartbeat run to fire (visible in logs as HEARTBEAT_RUN)
3. Send a user message within the heartbeat window
4. Observe the following in application logs:

   [heartbeat] HEARTBEAT_RUN triggered at 2024-01-15T10:30:01.234Z
   [steer] Injecting user message "What's the weather?" into heartbeat run
   [agent] Processing run #42 (heartbeat + steered message)
   [agent] Run #42 produced responses:
     - HEARTBEAT_OK (heartbeat ack)
     - TEXT: "The weather is sunny, 72°F"
   [outbound] Discarding run #42 responses (HEARTBEAT_OK detected)
   [channel] Delivered: HEARTBEAT_OK ack only (no user message)
   

5. User receives nothing—the TEXT response is never sent to Telegram

Diagnostic Evidence

The user-facing response exists in the session transcript with correct generation timestamps but never reaches the channel layer:

$ openclaw session show --id session-abc123
Session Transcript:
  [10:30:01.234] ← HEARTBEAT (scheduled)
  [10:30:02.456] ← USER: "What's the weather?" (steered into heartbeat run)
  [10:30:02.789] → HEARTBEAT_OK
  [10:30:03.012] → TEXT: "The weather is sunny, 72°F"  ← EXISTS IN TRANSCRIPT
  [10:30:03.100] ← Delivered: HEARTBEAT_OK only         ← MISSING TEXT

Workaround Verification

Switching to collect mode avoids the issue:

# config.yaml
messages:
  queue:
    mode: "collect"  # ← Workaround: queues as separate turn

In collect mode, the user message queues independently and receives its own run with full delivery.

Architectural Analysis: Run-Level Response Suppression

The issue stems from a fundamental design assumption in the heartbeat handling logic: a run containing HEARTBEAT_OK is classified as a "heartbeat no-op" and the entire run's outbound delivery is suppressed.

Failure Sequence

1. Steer Mode Injection: In steer mode, incoming user messages arriving during an active heartbeat run are injected into that run rather than creating a new one. This is intentional—steer prioritizes latency over isolation.
2. Multi-Response Run Generation: The agent processes the combined heartbeat + user message context and produces multiple responses in sequence:

   Response 1: HEARTBEAT_OK    // Agent acknowledges heartbeat with no action
   Response 2: TEXT           // Agent responds to user's actual question
   

3. Run Classification Logic: The run classification logic scans responses for any HEARTBEAT_* marker:

   // Simplified classification pseudocode
   function classifyRun(responses):
     for response in responses:
       if response.type.startsWith("HEARTBEAT_"):
         return RUN_TYPE.HEARTBEAT_NOOP  // ← Triggers suppression
     return RUN_TYPE.NORMAL
   

4. Premature Suppression: Because HEARTBEAT_OK is present, the entire run is marked as HEARTBEAT_NOOP, triggering discard logic in the outbound delivery layer:

   // Outbound delivery pseudocode
   function deliverResponses(run):
     if run.classification === RUN_TYPE.HEARTBEAT_NOOP:
       return  // ← Entire delivery skipped, including user response
     deliverToChannel(run.responses)
   

5. User Response Lost: The TEXT response (which is valid user-facing content) is discarded because it shares a run with HEARTBEAT_OK.

Code Location Reference

Why Collect Mode Works

In collect mode, the user message is queued as a separate followup turn. It receives its own independent run containing only user-facing responses—no HEARTBEAT_* markers—so the classification logic correctly identifies it as NORMAL and delivers it.

Option 1: Filter Responses Before Classification (Recommended)

Modify the run classification logic to ignore HEARTBEAT_OK responses when determining run type, allowing user-facing responses in the same run to be delivered.

Before

// src/runs/classifier.ts
function classifyRun(responses: Response[]): RunType {
  for (const response of responses) {
    if (response.type.startsWith("HEARTBEAT_")) {
      return RUN_TYPE.HEARTBEAT_NOOP;
    }
  }
  return RUN_TYPE.NORMAL;
}

After

// src/runs/classifier.ts
function classifyRun(responses: Response[]): RunType {
  const hasHeartbeatAction = responses.some(
    r => r.type.startsWith("HEARTBEAT_") && r.type !== "HEARTBEAT_OK"
  );
  const hasUserFacingResponse = responses.some(
    r => !r.type.startsWith("HEARTBEAT_") && r.type !== "CONTROL"
  );
if (hasHeartbeatAction && !hasUserFacingResponse) {
return RUN_TYPE.HEARTBEAT_NOOP;
}
return RUN_TYPE.NORMAL;
}

Option 2: Modify Outbound Delivery to Extract User Responses

If classification cannot be changed, modify the outbound delivery layer to extract and deliver non-heartbeat responses even from HEARTBEAT_NOOP runs.

// src/outbound/delivery.ts
function deliverResponses(run: Run): void {
  if (run.classification !== RUN_TYPE.HEARTBEAT_NOOP) {
    deliverToChannel(run.responses);
    return;
  }
  
  // Extract user-facing responses from heartbeat no-op runs
  const userResponses = run.responses.filter(
    r => !r.type.startsWith("HEARTBEAT_") && r.type !== "CONTROL"
  );
  
  if (userResponses.length > 0) {
    deliverToChannel(userResponses);
  }
}

Option 3: Configuration-Based Workaround

If code changes are not immediately possible, configure the system to avoid the condition:

# config.yaml
messages:
  queue:
    mode: "collect"  # Avoids steered injection into heartbeat runs
    
heartbeat:
  interval: 60s     # Reduces chance of user message arriving during heartbeat
  # Or disable heartbeat during active conversations:
  pause_on_active: true

Deployment Steps

1. Backup Configuration

   cp config.yaml config.yaml.backup

2. Apply Fix

   # If using Option 1 or 2:
   vim src/runs/classifier.ts   # or src/outbound/delivery.ts
   npm run build

3. Restart Service

   docker-compose down && docker-compose up -d
   # Or for systemd:
   sudo systemctl restart openclaw

4. Verify Configuration

   openclaw config show | grep -A5 "queue:"
   openclaw status

Test Case 1: Steered Message Delivery

Purpose: Verify that user messages injected into heartbeat runs are delivered.

# 1. Configure steer mode with short heartbeat
openclaw config set messages.queue.mode steer
openclaw config set heartbeat.interval 3s
openclaw restart

# 2. Monitor logs in one terminal
openclaw logs --follow | grep -E "(HEARTBEAT|steer|deliver)"

# 3. Send user message during heartbeat window
# Wait for log line: [heartbeat] HEARTBEAT_RUN triggered
# Then immediately send: "Testing steer delivery"

# 4. Verify delivery
# Expected: User receives response on Telegram
# Expected log: [outbound] Delivered: TEXT response to user

Success Criteria:

• User receives the response on Telegram
• Log shows Delivered: TEXT (not Discarded)
• Session transcript shows both HEARTBEAT_OK and TEXT responses

Test Case 2: Pure Heartbeat Still Suppressed

Purpose: Ensure that genuine HEARTBEAT_NOOP runs (without user messages) are still suppressed.

# 1. Wait for heartbeat to fire with NO user interaction
# Monitor logs for a clean heartbeat run

# 2. Expected log behavior
[heartbeat] HEARTBEAT_RUN triggered
[heartbeat] HEARTBEAT_OK generated (no user message)
[outbound] Discarding run (HEARTBEAT_NOOP)

# 3. Verify: User should NOT receive any notification from this run

Success Criteria:

• Heartbeat-only runs produce no user notification
• Log shows Discarding for pure heartbeat runs

Test Case 3: Session Transcript Validation

# Get session ID from a recent conversation
openclaw session list --limit 5
Show detailed transcript
openclaw session show –id <SESSION_ID> –verbose
Verify structure contains both response types
Expected output should show:
[timestamp] → HEARTBEAT_OK
[timestamp] → TEXT: “response content”
[timestamp] ← Delivered: HEARTBEAT_OK, TEXT  ← Both delivered

Regression Tests

# Run existing test suite
npm test -- --grep "heartbeat"
Run steer mode specific tests
npm test – –grep “steer”
Expected: All tests pass including:
- steer mode message injection
- heartbeat response classification
- outbound delivery filtering

Exit Code Verification

# After fix deployment
openclaw health check; echo "Exit code: $?"
# Expected: 0 (healthy)
Check service logs
docker-compose logs openclaw 2>&1 | tail -20
Expected: No ERROR level entries related to delivery

• HEARTBEAT_TIMEOUT — Heartbeat run exceeded maximum duration; may trigger session cleanup if consecutive timeouts exceed threshold

  [heartbeat] Run exceeded 30s timeout, forcing HEARTBEAT_TIMEOUT
  

• HEARTBEAT_SKIP — Heartbeat run skipped entirely due to active conversation; configuration heartbeat.pause_on_active: true

  [heartbeat] Skipping HEARTBEAT_RUN - active conversation detected
  

• STEER_INJECT_FAILED — Steer mode failed to inject message into active run; falls back to queuing

  [steer] Failed to inject message: no active heartbeat run in progress
  [steer] Falling back to queue for message "..."
  

• DELIVERY_FILTERED — Response was intentionally filtered by channel policy (spam detection, content filtering)

  [outbound] DELIVERY_FILTERED: response contains blocked keyword
  

• RATE_LIMIT_EXCEEDED — Telegram API rate limit hit; responses queued for retry

  [telegram] Rate limit exceeded (30/30), queuing response for retry in 60s
  

• QUEUE_MODE_CONFLICT — Conflicting queue mode settings between global and channel-specific config

  [config] Warning: telegram.queue_mode conflicts with messages.queue.mode
  

Historical Context

This issue represents a regression introduced when the run classification system was unified for efficiency. Previously, each response type had independent delivery logic, but the consolidation into run-level classification introduced the suppression behavior for multi-response runs containing HEARTBEAT_OK.

See Also

• OpenClaw Queue Modes Documentation — Detailed explanation of steer vs collect vs force
• Heartbeat System Architecture — Technical deep-dive on heartbeat scheduling and response handling
• Telegram Channel Adapter — Channel-specific delivery considerations