PR #73495: fix(telegram): document and warn when replyToMode silently disables tool-progress preview

• Repository: openclaw/openclaw
• Author: GodsBoy
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/73495

Description (problem / solution / changelog)

Summary

• Problem: Per docs/channels/telegram.md and docs/concepts/streaming.md, Telegram tool-progress preview updates have been documented as enabled by default since v2026.4.22. In practice, when channels.telegram.replyToMode != "off", the entire tool-progress preview path is silently disabled because answerLane.stream is never created. Users see zero Working… • tool: X lines and have no signal about why.
• Why it matters: This is a doc/runtime mismatch with no log warning, no doctor warning, and no doc note. It's already biting at least one user on the published 2026.4.26 build.
• What changed: Adds a new openclaw doctor warning that surfaces the silent disable at config time, and adds a <Note> callout in both telegram.md and streaming.md explaining the mutual exclusion.
• What did NOT change: No code change to extensions/telegram/src/bot-message-dispatch.ts. The runtime exclusion is architecturally sound (Telegram's quote-reply API requires the final message reference at send time, which is incompatible with preview-edit streaming); only the silence around it is the bug being fixed. Architectural decoupling (separate-message fallback when quote-reply is on) is intentionally deferred to a follow-up; called out as a suggested follow-up in the linked issue body.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #73487
• Related #71351 (default-flip churn for the same toolProgress key, then reversed pre-release)
• Related #71320 (origin "tool progress is too noisy" complaint that motivated #71351)
• This PR fixes a bug or regression

Root Cause

In extensions/telegram/src/bot-message-dispatch.ts:

const hasNativeQuoteReply = replyToMode !== "off" && Object.keys(replyQuoteByMessageId).length > 0;
const canStreamAnswerDraft = previewStreamingEnabled && !hasNativeQuoteReply && !accountBlockStreamingEnabled && !forceBlockStreamingForReasoning;
// ...
const lanes = { answer: createDraftLane("answer", canStreamAnswerDraft), reasoning: ... };
const answerLane = lanes.answer;
const previewToolProgressEnabled = Boolean(answerLane.stream) && resolveChannelStreamingPreviewToolProgress(telegramCfg);

When hasNativeQuoteReply === true:

• canStreamAnswerDraft is forced to false

• createDraftLane("answer", false) returns a lane with no stream

• answerLane.stream is undefined

• previewToolProgressEnabled = Boolean(undefined) && ... = false

• Every pushPreviewToolProgress(...) early-returns, silently dropping all tool events

• Root cause: quote-reply and preview-edit streaming are mutually exclusive at the Telegram API layer (quote-reply needs the final message reference at send time; preview-edit cannot supply one). The runtime exclusion is correct, but it is silent and undocumented.

• Missing detection / guardrail: no doctor warning surfacing the conflict between replyToMode != "off" and the documented-default streaming.preview.toolProgress: true. No log entry. No doc note about the exclusion.

• Contributing context: docs since v2026.4.22 claim tool-progress is enabled by default for Telegram. Users with the documented default config can spend hours hunting before realizing replyToMode was the cause.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/commands/doctor/shared/telegram-replyto-streaming.test.ts (new) and src/commands/doctor/shared/preview-warnings.test.ts (extended).
• Scenario the test should lock in: when channels.telegram.replyToMode != "off" and streaming.preview.toolProgress resolves to true (its documented default), collectDoctorPreviewWarnings() returns a warning string naming both keys, the affected paths (top-level + per-account), and the two remediation options.
• Why this is the smallest reliable guardrail: it locks in the exact decision the user-facing tool (openclaw doctor) reports, including per-account override inheritance. A runtime-side test would prove the silent-disable behavior, not the doctor's surfacing of it; which is what this PR fixes.
• Existing test that already covers this: none.

User-visible / Behavior Changes

• openclaw doctor now emits a single bundled warning when a Telegram channel has replyToMode != "off" and streaming.preview.toolProgress resolves true. The warning names every affected path (top-level + per-account), states the root cause in one sentence, and offers two remediations: set replyToMode: "off" to restore visibility, or set streaming.preview.toolProgress: false to acknowledge the trade-off and silence the warning.
• No runtime behavior change. Default Telegram behavior (when replyToMode = "off") is identical. Users who already have replyToMode != "off" continue to function exactly as today; they just get a one-line doctor warning explaining what they lose.
• Two new doc callouts (Telegram channel doc + cross-link from streaming concepts doc).

Diagram (if applicable)

N/A.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Read-only doctor scan over already-loaded config plus two doc additions. No code change in any runtime path.

Repro + Verification

Environment

• OS: Ubuntu 24.04 (cloud VPS)
• Runtime/container: Node 24 LTS, npm global install
• Model/provider: openai-codex (any Codex model that triggers tool calls)
• Integration/channel: Telegram (DM + topic)
• Relevant config (redacted):

{
  "channels": {
    "telegram": {
      "botToken": "<redacted>",
      "replyToMode": "first",
      "streaming": { "mode": "partial" }
    }
  }
}

Steps

1. Restart the gateway with the config above.
2. In a Telegram DM with the agent, send a prompt that requires a tool call (e.g. please run cat /etc/hostname and tell me the result).
3. Run openclaw doctor.

Expected

• During the run: Working… • tool: ... lines appear in the streaming preview while the tool is in flight (per docs/channels/telegram.md line ~280).
• openclaw doctor either reports no relevant warning, or it explicitly notes the configuration as expected.

Actual (before this PR)

• During the run: zero tool-progress lines visible. The agent eventually replies with the final answer; the user has no signal that any tool ran.
• openclaw doctor: no warning surfaces the silent disable.

Actual (after this PR)

• Runtime behavior unchanged (intentional, see Scope).
• openclaw doctor now emits:

- Telegram `streaming.preview.toolProgress` is enabled by default, but this config also sets `replyToMode != "off"`. Quote-reply requires the final message reference at send time, which is incompatible with preview-edit streaming, so tool-progress lines are silently dropped on every reply that quotes an inbound.
- channels.telegram: replyToMode: "first" (tool-progress preview will not render).
- To restore tool-progress visibility, set `replyToMode: "off"`.
- To keep quote-reply and acknowledge the trade-off, set `streaming.preview.toolProgress: false` to silence this warning.

Evidence

• Failing test/log before + passing after (live runtime instrumentation captured below)
• Trace/log snippets

The bug was confirmed by adding console.error markers to extensions/telegram/src/bot-message-dispatch.ts and re-running both states on the same gateway. Verbatim journalctl output:

With replyToMode: "first" (silent disable):

canStreamAnswerDraft=false | previewStreamingEnabled=true hasNativeQuoteReply=true accountBlockStreamingEnabled=false forceBlockStreamingForReasoning=false
dispatcher init: previewToolProgressEnabled=false answerLaneStream=false resolvedTP=true
pushPreviewToolProgress called: line="tool: process" enabled=false suppressed=false hasStream=false   <- dropped
pushPreviewToolProgress called: line="tool: session_status" enabled=false suppressed=false hasStream=false   <- dropped
[... 333 tool events fired by the agent runtime, all dropped at the bot dispatch gate ...]

With replyToMode: "off" (documented behavior):

canStreamAnswerDraft=true | previewStreamingEnabled=true hasNativeQuoteReply=false accountBlockStreamingEnabled=false forceBlockStreamingForReasoning=false
dispatcher init: previewToolProgressEnabled=true answerLaneStream=true resolvedTP=true
pushPreviewToolProgress called: line="exec" enabled=true suppressed=false hasStream=true   <- rendered
pushPreviewToolProgress called: line="tool: process" enabled=true suppressed=false hasStream=true   <- rendered
KILL-SWITCH FIRED: answerLane streaming text="Brave search for..." wiping 0 previewLines   <- clean transition to answer

The instrumentation was reverted before this PR was opened; the source files are pristine.

Human Verification (required)

• Verified scenarios:
  • Reproduced the silent-disable on the published 2026.4.26 build with replyToMode: "first" and observed zero tool-progress lines on multiple tool-using prompts.
  • Toggled to replyToMode: "off", restarted the gateway, and confirmed tool-progress lines render exactly as the docs describe (with the expected clean transition to the final answer).
  • Confirmed both states via the OCDBG trace above (top-level config + per-account paths).
  • Ran the new doctor warning against a real config containing replyToMode: "first" and verified it emits the expected single bundled warning string.
  • Ran pnpm test src/commands/doctor/shared/telegram-replyto-streaming.test.ts src/commands/doctor/shared/preview-warnings.test.ts (passes).
  • Ran pnpm check:changed end-to-end (exit 0 after pnpm install to refresh deps).
  • Ran pnpm config:docs:check (passes).
  • Ran git diff --check on the docs additions (clean).
• Edge cases checked:
  • replyToMode = "all" and replyToMode = "batched" also trigger the warning (documented as part of the mutual exclusion in the doc note).
  • Per-account replyToMode overrides are flagged separately from top-level.
  • Per-account configs that omit replyToMode correctly inherit the top-level value for the warning calculation.
  • Explicit streaming.preview.toolProgress: false opt-out correctly suppresses the warning at both top-level and per-account.
  • streaming.mode: "off" (preview path inactive anyway) correctly suppresses the warning.
• What I did NOT verify:
  • Discord and Slack channels likely have an analogous previewStreamingEnabled && !hasNativeQuoteReply family pattern, but the same silent-disable claim has not been verified there. This PR is intentionally Telegram-scoped; the linked issue notes Discord/Slack parity as a candidate follow-up.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: users who explicitly want quote-reply and have accepted no tool-progress will see a new doctor warning each run.
  • Mitigation: the warning text includes the explicit opt-out (streaming.preview.toolProgress: false) so users can acknowledge the trade-off and silence the warning permanently.
• Risk: per-account configs with deeper nesting (group/topic-scoped overrides) may not be fully covered by the current scan.
  • Mitigation: the scan iterates the top-level + accounts.* shape that matches the runtime resolver. Tests assert top-level + per-account behavior. Deeper-scoped overrides would be a focused follow-up if the maintainers want broader coverage.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/channels/telegram.md (modified, +4/-0)
• docs/concepts/streaming.md (modified, +1/-0)
• extensions/active-memory/index.test.ts (modified, +2/-2)
• src/commands/doctor/shared/preview-warnings.test.ts (modified, +40/-0)
• src/commands/doctor/shared/preview-warnings.ts (modified, +15/-0)
• src/commands/doctor/shared/telegram-replyto-streaming.test.ts (added, +214/-0)
• src/commands/doctor/shared/telegram-replyto-streaming.ts (added, +117/-0)

PR #73508: docs(channels,telegram): note replyToMode mutually excludes preview tool-progress

• Repository: openclaw/openclaw
• Author: wenxu007
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/73508

Description (problem / solution / changelog)

Summary

Documents the runtime mutual exclusion between Telegram native quote replies (channels.telegram.replyToMode != "off" with a quotable original message) and the answer-lane preview stream that powers streaming.preview.toolProgress (Working… • tool: … lines), so users who want live tool-progress visibility know to keep replyToMode: "off" for now.

Background

Per the issue, the docs say streaming.preview.toolProgress is enabled by default since v2026.4.22, but in practice — when channels.telegram.replyToMode is anything other than "off" and the turn uses a native quote reply — the answer-lane preview stream is never created. The reporter traced this in extensions/telegram/src/bot-message-dispatch.ts:

const hasNativeQuoteReply =
  replyToMode !== "off" && Object.keys(replyQuoteByMessageId).length > 0;
const canStreamAnswerDraft =
  previewStreamingEnabled &&
  !hasNativeQuoteReply &&
  !accountBlockStreamingEnabled &&
  !forceBlockStreamingForReasoning;
// ...
const previewToolProgressEnabled =
  Boolean(answerLane.stream) &&
  resolveChannelStreamingPreviewToolProgress(telegramCfg);

Telegram's native quote reply requires the final message reference at send time, which is incompatible with the preview-edit model used for tool-progress lines. The architectural reason is sound; the issue called out that the silent disablement is undocumented.

Change

Doc-only, no runtime behavior change. Two cross-referenced notes added to docs/channels/telegram.md:

• In the Streaming accordion, right after the streaming.preview.toolProgress configuration example, a !!! warning callout explains that quote-reply turns produce no Working… lines and points users at replyToMode: "off".
• In the Reply threading tags accordion (where replyToMode is documented), a complementary !!! info callout repeats the constraint from the threading-config side so it is discoverable from either entry point.

Both notes link back to #73487.

Notes

• Followups for the maintainers (out of scope here): an openclaw doctor warning when both replyToMode != "off" and streaming.preview.toolProgress: true are configured, or an architectural fallback that delivers tool-progress as separate persistent messages when quote-reply blocks the preview path. Keeping this PR doc-only so it can land independent of those decisions.

Closes #73487.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/channels/telegram.md (modified, +6/-0)