fix(telegram): honor DM allowlist aliases

[ericksoa]

Summary

• Treat TELEGRAM_AUTHORIZED_CHAT_IDS and TELEGRAM_CHAT_ID as compatibility aliases for TELEGRAM_ALLOWED_IDS, while persisting and baking only the canonical TELEGRAM_ALLOWED_IDS value.
• Preserve alias handling across fresh onboard, channels add telegram, resume/rebuild, and OpenClaw config generation so Telegram DMs get dmPolicy: allowlist / allowFrom when QA-style env vars are used.
• Add Telegram runtime breadcrumbs for DM allowlist state, inbound getUpdates metadata, and outbound sendMessage attempts without logging tokens, IDs, or message text.
• Add an opt-in live Telegram inbound reply validation surface that uses an allowlist alias, waits for a real Telegram-client DM, and verifies both inbound and outbound gateway breadcrumbs.
• Update messaging docs and generated skill references with the alias and inbound-test guidance.

Related Issue

Closes #4553

Problem

The #4553 repro exported TELEGRAM_CHAT_ID and TELEGRAM_AUTHORIZED_CHAT_IDS, but NemoClaw only consumed TELEGRAM_ALLOWED_IDS when constructing the OpenClaw allowFrom map. That made the bridge look healthy because polling started, while the rebuilt sandbox could still have no explicit DM allowlist. The repro also used Telegram Bot API sendMessage, which sends from the bot to the chat and therefore proves outbound API access, not inbound user-to-agent routing.

Live Inbound Validation Surface

To reproduce the user-visible acceptance path with a real Telegram client and an alias-derived allowlist:

TELEGRAM_BOT_TOKEN_REAL=<real-bot-token> \
TELEGRAM_AUTHORIZED_CHAT_IDS=<allowed-telegram-user-or-private-chat-id> \
NEMOCLAW_TELEGRAM_INBOUND_REPLY_E2E=1 \
NEMOCLAW_NON_INTERACTIVE=1 \
NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1 \
NVIDIA_API_KEY=<key> \
bash test/e2e/test-messaging-providers.sh

When the script prompts, send a fresh direct message from the allowed Telegram client to the bot. The check then waits for both [telegram] [default] inbound update received and [telegram] [default] outbound sendMessage attempted in /tmp/gateway.log.

Verification

• npm run build:cli
• npm run typecheck:cli
• npx vitest run src/lib/messaging-channel-config.test.ts src/lib/onboard/messaging-config.test.ts src/lib/onboard/messaging-channel-setup.test.ts src/lib/actions/sandbox/telegram-channel-bridge-verification.test.ts test/generate-openclaw-config.test.ts test/telegram-diagnostics.test.ts --testTimeout 60000
• npx vitest run test/telegram-diagnostics.test.ts --testTimeout 60000
• npx vitest run --project cli test/repro-2666-silent-list-status.test.ts --testTimeout 15000
• npx prek run shfmt biome-format --files test/e2e/test-messaging-providers.sh --stage pre-push
• bash -n test/e2e/test-messaging-providers.sh
• shellcheck test/e2e/test-messaging-providers.sh
• npm run docs:strict (0 errors, 2 existing Fern warnings hidden by default)
• git diff --check

Nightly E2E

Current head: fb394dd95129022d0835ce024c2f4573db74bc1f.

Selected PR-head nightly passed: https://github.com/NVIDIA/NemoClaw/actions/runs/26669565696

Required jobs passed:

• messaging-providers-e2e
• channels-add-remove-e2e
• messaging-compatible-endpoint-e2e

Older selected runs at 66be908cc2efdd37b9a6ae4ad6668409a6a2d673, fdec626e8ddfed3f1de1a9000fbfcaf18ad9fc8b, and c08a458ccf970c0f35bb9ea4e5f2fd1809be573b are superseded.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds alias-aware Telegram messaging config resolution (canonicalizes legacy keys into TELEGRAM_ALLOWED_IDS), backfills and warns in onboarding/post-rebuild flows, emits runtime diagnostics for Bot API sendMessage/getUpdates and config state, updates e2e scripts for alias handling and optional inbound-reply probes, expands tests, and updates docs.

Changes

Telegram messaging DM allowlist aliases and diagnostics

Layer / File(s)	Summary
Messaging config aliasing infrastructure src/lib/messaging-channel-config.ts, src/lib/messaging-channel-config.test.ts	Introduce CONFIG_ALIASES, alias->canonical lookup, resolveMessagingChannelConfigEnvValue, and make sanitize/read/hydrate alias-aware. Tests verify canonical precedence, canonicalization from aliases, and hydration into TELEGRAM_ALLOWED_IDS.
Config resolution in onboarding flows src/lib/onboard/messaging-channel-setup.ts, src/lib/onboard/messaging-config.ts, src/lib/onboard/messaging-channel-setup.test.ts, src/lib/onboard/messaging-config.test.ts	Use alias-aware resolver in onboarding/build flows, backfill canonical env keys when aliases are used, and warn when legacy keys are detected. Tests assert non-interactive setup accepts aliases and build config prefers canonical values.
Runtime diagnostics and telemetry nemoclaw-blueprint/scripts/telegram-diagnostics.js, test/telegram-diagnostics.test.ts, test/generate-openclaw-config.test.ts	Add runtime breadcrumbs to log DM allowlist state (without exposing IDs), outbound sendMessage response status, and inbound getUpdates observations once per process. Tests verify diagnostics output and safe logging.
Post-rebuild bridge verification src/lib/actions/sandbox/telegram-channel-bridge-verification.ts, src/lib/actions/sandbox/telegram-channel-bridge-verification.test.ts, src/lib/actions/sandbox/policy-channel.ts	New helpers to select default Telegram account and print an allowlist-empty warning; wire the warning into verifyChannelBridgeAfterRebuild to emit targeted guidance after bridge startup. Tests cover selection and conditional warning emission.
E2E script normalization and gating test/e2e/test-messaging-providers.sh	Accept TELEGRAM_AUTHORIZED_CHAT_IDS and TELEGRAM_CHAT_ID as compatibility aliases, choose a single allowlist source and export normalized env, count and report parsed IDs, skip onboarding reachability when using fake tokens, and add an optional live inbound-reply probe gated to real tokens and alias-path usage.
User documentation for aliases and troubleshooting docs/manage-sandboxes/messaging-channels.mdx, docs/reference/troubleshooting.mdx, skills/.../messaging-channels.md, skills/.../troubleshooting.md	Document TELEGRAM_ALLOWED_IDS as canonical, list legacy aliases, and clarify that outbound sendMessage only validates API delivery while inbound agent reply testing requires messaging from an allowed user and checking gateway logs.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4288: Related Telegram diagnostics changes and test expectations.
• NVIDIA/NemoClaw#4403: Related telemetry/startup probe improvements in telegram-diagnostics.js.

Suggested labels

Integration: Telegram, documentation

"🐰 I hopped through configs, tidy and bright,
Aliases folded to one shining light,
Warnings whispered when lists are bare,
Breadcrumbs trace the outbound air,
Now chats and docs spring clearer, day and night."

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.06% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(telegram): honor DM allowlist aliases' accurately summarizes the main change: adding support for Telegram DM allowlist aliases (TELEGRAM_AUTHORIZED_CHAT_IDS and TELEGRAM_CHAT_ID) to work alongside the canonical TELEGRAM_ALLOWED_IDS key.
Linked Issues check	✅ Passed	The PR comprehensively addresses all coding requirements from issue #4553: accepting alias env vars (TELEGRAM_CHAT_ID, TELEGRAM_AUTHORIZED_CHAT_IDS) so allowFrom DM allowlist is correctly populated, adding runtime breadcrumbs for inbound/outbound diagnostics, implementing allowlist verification, and providing E2E validation for inbound routing.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to Telegram DM allowlist alias support and inbound routing diagnostics as specified in #4553, including config normalization, documentation updates, diagnostics instrumentation, and E2E testing.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/telegram-allowed-id-aliases

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-4554.docs.buildwithfern.com/nemoclaw

[github-actions]

E2E Advisor Recommendation

Required E2E: messaging-providers-e2e, channels-add-remove-e2e, messaging-compatible-endpoint-e2e
Optional E2E: ubuntu-repo-cloud-openclaw-telegram, token-rotation-e2e

Dispatch hint: messaging-providers-e2e,channels-add-remove-e2e,messaging-compatible-endpoint-e2e

Auto-dispatched E2E: messaging-providers-e2e, channels-add-remove-e2e, messaging-compatible-endpoint-e2e via nightly-e2e.yaml at fb394dd95129022d0835ce024c2f4573db74bc1f — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• messaging-providers-e2e (high (~75 min timeout; creates a real sandbox and exercises multiple messaging providers)): Directly covers the changed messaging provider/onboarding path: Telegram allowlist alias handling, provider/placeholder/L7 rewrite, baked openclaw.json channel config, Telegram diagnostics, and the modified test/e2e/test-messaging-providers.sh script.
• channels-add-remove-e2e (high (~75 min timeout; real sandbox lifecycle)): Required because policy-channel.ts changed the channels add post-rebuild verification path for Telegram. This job validates host-side channels add/remove, automatic policy preset application, rebuild, provider attachment, and Telegram bridge egress after lifecycle mutations.
• messaging-compatible-endpoint-e2e (medium (single sandbox with hermetic compatible endpoint)): Required because telegram-diagnostics.js now emits breadcrumbs around Telegram inbound/outbound traffic and inference.local failures. This job is the existing hermetic Telegram + OpenAI-compatible endpoint routing check for the bridge-to-inference user flow.

Optional E2E

• ubuntu-repo-cloud-openclaw-telegram (high (scenario E2E with cloud OpenClaw and Telegram secret requirements)): Useful real-flow confidence for OpenClaw with Telegram messaging enabled through the typed scenario runner. It is adjacent to the changed Telegram DM allowlist and diagnostics behavior, but may require real Telegram secrets and is less targeted than messaging-providers-e2e.
• token-rotation-e2e (high (real sandbox and multiple messaging providers)): Optional adjacent coverage for persisted messaging configuration and provider credential hash behavior across repeated onboarding/rebuilds. The PR changes config sanitization/hydration but does not directly change token rotation logic.

New E2E recommendations

• Telegram inbound reply diagnostics (high): The PR adds runtime diagnostics for inbound getUpdates and outbound sendMessage breadcrumbs, but the existing live inbound proof in test/e2e/test-messaging-providers.sh is optional and human-prompted via NEMOCLAW_TELEGRAM_INBOUND_REPLY_E2E. A hermetic fake Telegram getUpdates/sendMessage loop would make this merge-blocking without requiring a human Telegram client.
  • Suggested test: Add a hermetic Telegram inbound-reply E2E that drives a controlled Bot API mock returning getUpdates payloads and asserts the gateway logs both inbound update received and outbound sendMessage attempted.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: messaging-providers-e2e,channels-add-remove-e2e,messaging-compatible-endpoint-e2e

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: ubuntu-repo-cloud-openclaw-telegram
Optional scenario E2E: None

Dispatch required scenario E2E:

• gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-telegram

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• ubuntu-repo-cloud-openclaw-telegram: Changes affect Telegram messaging onboarding/config canonicalization, baked OpenClaw Telegram bridge diagnostics, and post-rebuild Telegram bridge verification. The routed Telegram OpenClaw scenario is the smallest scenario ID that exercises the affected messaging onboarding and messaging-telegram validation surface.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw-telegram

Optional scenario E2E

• None.

Relevant changed files

• nemoclaw-blueprint/scripts/telegram-diagnostics.js
• src/lib/actions/sandbox/policy-channel.ts
• src/lib/actions/sandbox/telegram-channel-bridge-verification.ts
• src/lib/messaging-channel-config.ts
• src/lib/onboard/messaging-channel-setup.ts
• src/lib/onboard/messaging-config.ts

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26668622469
Target ref: 66be908cc2efdd37b9a6ae4ad6668409a6a2d673
Workflow ref: main
Requested jobs: messaging-providers-e2e,telegram-injection-e2e,network-policy-e2e
Summary: 0 passed, 0 failed, 0 skipped

Job	Result
messaging-providers-e2e	⚠️ cancelled
network-policy-e2e	⚠️ cancelled
telegram-injection-e2e	⚠️ cancelled

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 3 worth checking, 0 nice ideas
Since last review: 1 prior item resolved, 2 still apply, 0 new items found

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• Source-of-truth review needed: Telegram runtime diagnostics preload: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: nemoclaw-blueprint/scripts/telegram-diagnostics.js wraps http/https request methods and stderr; the comments describe diagnostic purpose but not the removal condition.
• Telegram live inbound proof still does not correlate the DM to the agent reply (test/e2e/test-messaging-providers.sh:555): The optional live proof improves coverage by requiring an alias-derived allowlist and waiting for both an inbound getUpdates breadcrumb and an outbound sendMessage breadcrumb after a log baseline. It still accepts any inbound breadcrumb and any outbound sendMessage breadcrumb after that baseline, without proving the outbound send was caused by the fresh Telegram-client DM, passed through an agent turn, or reached the client as a visible reply. That leaves the linked issue's acceptance clauses about routing the message to the agent and receiving a client-visible reply only partially evidenced.
  • Recommendation: Strengthen M19b by correlating the fresh DM to the reply. For example, use a sanitized/generated nonce or non-sensitive correlation token, assert an agent-turn breadcrumb between inbound and outbound, or otherwise bind the observed sendMessage to the specific update being tested.
  • Evidence: run_telegram_inbound_reply_probe records log_before_lines, then sets saw_inbound when delta logs contain "[telegram] [default] inbound update received" and saw_outbound when they contain "[telegram] [default] outbound sendMessage attempted"; the pass at line 563 requires only both booleans.
• Telegram diagnostics monkeypatch still lacks an explicit source-of-truth lifecycle (nemoclaw-blueprint/scripts/telegram-diagnostics.js:244): The PR expands a NODE_OPTIONS preload that globally wraps http/https request methods and stderr to observe Telegram runtime traffic. The implementation has useful mitigations: it filters to api.telegram.org, caps getUpdates buffering, emits one-shot sanitized breadcrumbs, and tests token/ID/message redaction. However, this remains a sensitive sandbox-runtime monkeypatch, and the code/docs still do not state when the workaround should move to provider-native diagnostics or be removed.
  • Recommendation: Document the source boundary and removal condition near the preload, such as keeping this only until OpenClaw emits provider-native sanitized inbound/outbound/allowlist breadcrumbs, then removing or narrowing the monkeypatch. If the diagnostic read paths continue to grow, also add a malformed-config/no-crash regression test for the new best-effort config reads.
  • Evidence: telegram-diagnostics.js installs wrapHttp(http, "request"), wrapHttp(http, "get"), wrapHttp(https, "request"), and wrapHttp(https, "get") before the gateway-specific startup timer gate; tests cover redaction but no explicit removal condition is present.

🌱 Nice ideas

• None.

Since last review details

Current findings:

• Source-of-truth review needed: Telegram runtime diagnostics preload: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: nemoclaw-blueprint/scripts/telegram-diagnostics.js wraps http/https request methods and stderr; the comments describe diagnostic purpose but not the removal condition.
• Telegram live inbound proof still does not correlate the DM to the agent reply (test/e2e/test-messaging-providers.sh:555): The optional live proof improves coverage by requiring an alias-derived allowlist and waiting for both an inbound getUpdates breadcrumb and an outbound sendMessage breadcrumb after a log baseline. It still accepts any inbound breadcrumb and any outbound sendMessage breadcrumb after that baseline, without proving the outbound send was caused by the fresh Telegram-client DM, passed through an agent turn, or reached the client as a visible reply. That leaves the linked issue's acceptance clauses about routing the message to the agent and receiving a client-visible reply only partially evidenced.
  • Recommendation: Strengthen M19b by correlating the fresh DM to the reply. For example, use a sanitized/generated nonce or non-sensitive correlation token, assert an agent-turn breadcrumb between inbound and outbound, or otherwise bind the observed sendMessage to the specific update being tested.
  • Evidence: run_telegram_inbound_reply_probe records log_before_lines, then sets saw_inbound when delta logs contain "[telegram] [default] inbound update received" and saw_outbound when they contain "[telegram] [default] outbound sendMessage attempted"; the pass at line 563 requires only both booleans.
• Telegram diagnostics monkeypatch still lacks an explicit source-of-truth lifecycle (nemoclaw-blueprint/scripts/telegram-diagnostics.js:244): The PR expands a NODE_OPTIONS preload that globally wraps http/https request methods and stderr to observe Telegram runtime traffic. The implementation has useful mitigations: it filters to api.telegram.org, caps getUpdates buffering, emits one-shot sanitized breadcrumbs, and tests token/ID/message redaction. However, this remains a sensitive sandbox-runtime monkeypatch, and the code/docs still do not state when the workaround should move to provider-native diagnostics or be removed.
  • Recommendation: Document the source boundary and removal condition near the preload, such as keeping this only until OpenClaw emits provider-native sanitized inbound/outbound/allowlist breadcrumbs, then removing or narrowing the monkeypatch. If the diagnostic read paths continue to grow, also add a malformed-config/no-crash regression test for the new best-effort config reads.
  • Evidence: telegram-diagnostics.js installs wrapHttp(http, "request"), wrapHttp(http, "get"), wrapHttp(https, "request"), and wrapHttp(https, "get") before the gateway-specific startup timer gate; tests cover redaction but no explicit removal condition is present.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@nemoclaw-blueprint/scripts/telegram-diagnostics.js`:
- Around line 159-164: The current logic emits the "DM allowlist is empty"
warning unconditionally; restrict that warning to only run when account.dmPolicy
=== 'allowlist'. Change the block around account.dmPolicy and allowFrom so that
you check account.dmPolicy === 'allowlist' first, then inside that branch emit
the configured message when allowFrom.length > 0 and emit the "allowlist is
empty" warning only when allowFrom.length === 0; keep the existing emit messages
and the allowFrom length pluralization logic intact (refer to account.dmPolicy,
allowFrom and the emit calls).

In `@src/lib/actions/sandbox/policy-channel.ts`:
- Around line 599-603: The warning currently triggers when account?.dmPolicy !==
"allowlist" or allowFrom.length === 0, causing false positives; update the
condition in the block that logs the Telegram allowlist warning (where
account?.dmPolicy and allowFrom are referenced in policy-channel.ts) to only run
when account?.dmPolicy === "allowlist" && allowFrom.length === 0 so the message
about an empty allowlist is emitted only when allowlist mode is active and there
are no allowed senders.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 14be2789-68ba-4da2-8047-83a9cc901e02

📥 Commits

Reviewing files that changed from the base of the PR and between a5e7e63 and 66be908.

📒 Files selected for processing (14)

• docs/manage-sandboxes/messaging-channels.mdx
• docs/reference/troubleshooting.mdx
• nemoclaw-blueprint/scripts/telegram-diagnostics.js
• skills/nemoclaw-user-manage-sandboxes/references/messaging-channels.md
• skills/nemoclaw-user-reference/references/troubleshooting.md
• src/lib/actions/sandbox/policy-channel.ts
• src/lib/messaging-channel-config.test.ts
• src/lib/messaging-channel-config.ts
• src/lib/onboard/messaging-channel-setup.test.ts
• src/lib/onboard/messaging-channel-setup.ts
• src/lib/onboard/messaging-config.test.ts
• src/lib/onboard/messaging-config.ts
• test/generate-openclaw-config.test.ts
• test/telegram-diagnostics.test.ts

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26668726735
Target ref: 66be908cc2efdd37b9a6ae4ad6668409a6a2d673
Workflow ref: main
Requested jobs: messaging-providers-e2e,channels-add-remove-e2e
Summary: 0 passed, 0 failed, 0 skipped

Job	Result
channels-add-remove-e2e	⚠️ cancelled
messaging-providers-e2e	⚠️ cancelled

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26669016534
Target ref: fdec626e8ddfed3f1de1a9000fbfcaf18ad9fc8b
Workflow ref: main
Requested jobs: messaging-providers-e2e,channels-add-remove-e2e
Summary: 0 passed, 0 failed, 0 skipped

Job	Result
channels-add-remove-e2e	⚠️ cancelled
messaging-providers-e2e	⚠️ cancelled

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26669332308
Target ref: c08a458ccf970c0f35bb9ea4e5f2fd1809be573b
Workflow ref: main
Requested jobs: messaging-providers-e2e,channels-add-remove-e2e
Summary: 0 passed, 0 failed, 0 skipped

Job	Result
channels-add-remove-e2e	⚠️ cancelled
messaging-providers-e2e	⚠️ cancelled

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 26669565696
Target ref: fb394dd95129022d0835ce024c2f4573db74bc1f
Workflow ref: main
Requested jobs: messaging-providers-e2e,channels-add-remove-e2e,messaging-compatible-endpoint-e2e
Summary: 3 passed, 0 failed, 0 skipped

Job	Result
channels-add-remove-e2e	✅ success
messaging-compatible-endpoint-e2e	✅ success
messaging-providers-e2e	✅ success