Telegram Outage Debug (OpenClaw)

Goal: turn “bot 不回了” into a precise classification + timeline + next action.

This skill assumes default OpenClaw paths:

• •Config: ~/.openclaw/openclaw.json
• •Logs:
  • •~/.openclaw/logs/gateway.log
  • •~/.openclaw/logs/gateway.err.log

Mental model (3 hops)

For any Telegram message that should produce a reply:

1. •Inbound Telegram → OpenClaw (polling/webhook)
2. •LLM OpenClaw → model provider
3. •Outbound OpenClaw → Telegram (sendMessage / sendChatAction)

“Bot 不回” can be caused by failure in ANY hop.

First decision: DM vs Group

DM (private chat)

Common blockers:

• •dmPolicy: pairing (needs pairing approve)
• •dmPolicy: allowlist + sender not in allowFrom
• •outbound sendMessage failure (network)
• •LLM timeout

Group / Topic

Common blockers:

• •requireMention: true (expected: only replies when mentioned)
• •BotFather privacy mode blocks non-mention group messages even if config says requireMention:false
• •group allowlist / groupPolicy / allowFrom not-allowed
• •outbound sendMessage failure

Quick classification checklist (fast)

Run these (CLI is node-based here):

openclaw gateway status
openclaw channels status --probe --timeout 20000
openclaw pairing list telegram

Interpretation:

• •If Telegram account shows not running / 409 → token conflict.
• •If DM is pairing and sender not approved → you’ll often see a pairing request (sometimes bot can’t deliver pairing message if outbound is broken).
• •If channels status --probe says works, provider/token are likely OK; focus on outbound/network or LLM.

Log triage: the handful of lines that matter

A) Token conflict (two pollers) → 409

Look for: 409, Conflict, terminated by other getUpdates request.

B) Outbound to Telegram failing (network)

Look for:

• •sendMessage failed: Network request for 'sendMessage' failed!
• •sendChatAction failed: Network request for 'sendChatAction' failed!
• •TypeError: fetch failed

This means: reply may be generated but cannot be delivered.

C) LLM slow/timeout

Look for:

• •FailoverError: LLM request timed out
• •lane wait exceeded / embedded run timeout

This means: inbound received, but model step did not finish.

D) Config gating / allowlist

Look for:

• •not-allowed
• •skipping group message
• •requireMention gating notes

Build a timeline from logs (recommended)

Use the bundled script to extract a window around a local timestamp.

Script

• •scripts/extract-window.sh

Example (PST):

cd ~/.openclaw/workspace-claw-config/skills/telegram-outage-debug
./scripts/extract-window.sh \
  --local "2026-02-03 00:36" --tz "America/Los_Angeles" --minutes 10 --tail 800000 \
  --grep "telegram|sendMessage failed|sendChatAction failed|fetch failed|409|Conflict|pairing|not-allowed|LLM request timed out"

Tip: logs can be multi-GB; increase/decrease --tail depending on how far back you’re debugging.

Outputs:

• •a UTC window
• •matching lines from gateway.err.log and gateway.log

Explanation template (use in chat)

When reporting to the user, keep it short and structured:

• •Impact: DM/group, which bot/account, since when.
• •Evidence: 2–6 log lines (timestamps included).
• •Classification: 409 token conflict vs pairing gating vs outbound network vs LLM timeout vs config gating.
• •Next action: 1–3 commands or one config patch.

Temporary deep debug (only when needed)

If the outage is intermittent and fetch failed doesn’t show the underlying errno/status, temporarily enable HTTP diagnostics.

Process (ask before changing config):

1. •backup ~/.openclaw/openclaw.json
2. •set diagnostics.flags=["telegram.http","gateway.*"]
3. •restart gateway
4. •reproduce once
5. •extract only the relevant block
6. •revert diagnostics flags and restart

The goal is to capture:

• •HTTP status / Telegram error description
• •whether request had the expected chat_id / message_thread_id
• •underlying errno (timeout/reset/DNS)