fix(telegram): eliminate BOT_COMMANDS_TOO_MUCH double-log, cap commands at 99, add network retry

[Copilot]

On every gateway start, setMyCommands could produce two redundant error lines for the same failure, with no actionable guidance and no retry distinction.

Summary

• Problem: BOT_COMMANDS_TOO_MUCH (GrammyError 400) double-logged on every startup — once from withTelegramApiErrorLogging (shouldLog fired for all non-network errors) and again from the outer void sync().catch(...). No command count cap existed, so any configuration with ≥100 commands hit this on every run.
• Why it matters: Noisy duplicate errors, no fix guidance, bot silently loses its command menu.
• What changed: Cap commands at 99 before calling setMyCommands; suppress withTelegramApiErrorLogging for non-recoverable API errors; detect BOT_COMMANDS_TOO_MUCH explicitly and emit one actionable message then return (no retry, no rethrow). Added exponential-backoff retry for genuine network errors only.
• What did NOT change: All handler registration, command routing, deleteMyCommands behavior, retry policy shape.

Before:

[telegram] telegram setMyCommands failed: Call to 'setMyCommands' failed! (400: Bad Request: BOT_COMMANDS_TOO_MUCH)
[telegram] command sync failed: GrammyError: Call to 'setMyCommands' failed! (400: Bad Request: BOT_COMMANDS_TOO_MUCH)

After:

[telegram] Telegram command sync failed: too many commands (BOT_COMMANDS_TOO_MUCH). 15 command(s) were sent; if this persists, try disabling native commands with channels.telegram.commands.native: false or reducing plugin/custom commands.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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

• Related #

User-visible / Behavior Changes

• BOT_COMMANDS_TOO_MUCH now surfaces as a single error with channels.telegram.commands.native: false guidance instead of two raw GrammyError dumps.
• Configurations with >99 commands now log a warning and register the first 99; previously they would error on every start.
• Transient network errors on setMyCommands now retry up to 5× with exponential backoff (3s→60s) before failing; previously they surfaced immediately.

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

Repro + Verification

Environment

• Integration/channel: Telegram Bot API
• Relevant config: any channels.telegram config with enough native/plugin/custom commands to reach the cap

Steps

1. Configure bot with ≥100 commands (or trigger a stale command scope)
2. openclaw gateway run
3. Observe logs

Expected

• Single line with count and actionable config guidance

Actual (before fix)

• Two raw GrammyError lines, no guidance, no retry distinction

Evidence

• Failing test/log before + passing after

10 unit tests in bot-native-command-menu.test.ts covering: cap enforcement, single-log path, no-retry for BOT_COMMANDS_TOO_MUCH, abort signal, exhausted network retries, deleteMyCommands suppression.

Human Verification (required)

• Verified scenarios: BOT_COMMANDS_TOO_MUCH single-log; cap at 99 with overflow warning; no retry on API errors; retry + backoff on network errors; abort signal exits cleanly
• Edge cases checked: non-BOT_COMMANDS_TOO_MUCH non-network errors still propagate to outer catch; commandsToRegister.length === 0 returns early without calling setMyCommands
• What you did not verify: live Telegram environment with actual command overflow

Compatibility / Migration

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

Failure Recovery (if this breaks)

• Revert src/telegram/bot-native-command-menu.ts and src/telegram/bot-native-commands.ts
• Known bad symptoms: BOT_COMMANDS_TOO_MUCH silently swallowed with no log — confirm the single actionable line still appears on overflow

Risks and Mitigations

• Risk: isTelegramBotCommandsTooMuch string-matches .description/.message — future grammY error shape changes could miss detection
  • Mitigation: both fields checked; outer .catch() remains as fallback so undetected shapes still produce "Telegram command sync failed: …"

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.