diff --git a/CHANGELOG.md b/CHANGELOG.md index 2a55b7342bf..12091267c35 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ Docs: https://docs.openclaw.ai - Cron/Telegram: preserve explicit `:topic:` delivery targets over stale session-derived thread IDs when isolated cron announces to Telegram forum topics. Carries forward #59069; refs #49704 and #43808. Thanks @roytong9. - CLI/model probes: reject empty or whitespace-only `infer model run --prompt` values before calling local providers or the Gateway, so smoke checks do not spend provider calls on invalid turns. Fixes #73185. Thanks @iot2edge. - Gateway/media: route text-only `chat.send` image offloads through media-understanding fields so `agents.defaults.imageModel` can describe WebChat attachments instead of leaving only an opaque `media://inbound` marker. Fixes #72968. Thanks @vorajeeah. +- Channels/Telegram: fail fast when Telegram rejects the startup `getMe` token probe with 401, so invalid or stale BotFather tokens are reported as token auth failures instead of misleading `deleteWebhook` cleanup failures. Fixes #47674. Thanks @samaedan-arch. - CLI/onboarding: infer image input for common custom-provider vision model IDs, ask only for unknown models, and keep `--custom-image-input`/`--custom-text-input` overrides so vision-capable proxies do not get saved as text-only configs. Fixes #51869. Thanks @Antsoldier1974. - Models/OpenAI Codex: stop listing or resolving unsupported `openai-codex/gpt-5.4-mini` rows through Codex OAuth, keep stale discovery rows suppressed with a clear API-key-route hint, and leave direct `openai/gpt-5.4-mini` available. Fixes #73242. Thanks @0xCyda. - Plugin SDK: restore the root-alias bridge for `registerContextEngine` and expose missing legacy compat helpers `normalizeAccountId` and `resolvePreferredOpenClawTmpDir` so older external plugins such as `openclaw-weixin` can keep loading while migrating to focused SDK subpaths. Fixes #53497. Thanks @alanxchen85. diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index f540e2d99e2..8fb7ec2be79 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -365,6 +365,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `setMyCommands failed` with `BOT_COMMANDS_TOO_MUCH` means the Telegram menu still overflowed after trimming; reduce plugin/skill/custom commands or disable `channels.telegram.commands.native`. - `deleteWebhook`, `deleteMyCommands`, or `setMyCommands` failing with `404: Not Found` while direct Bot API curl commands work can mean `channels.telegram.apiRoot` was set to the full `/bot` endpoint. `apiRoot` must be only the Bot API root, and `openclaw doctor --fix` removes an accidental trailing `/bot`. + - `getMe returned 401` means Telegram rejected the configured bot token. Update `botToken`, `tokenFile`, or `TELEGRAM_BOT_TOKEN` with the current BotFather token; OpenClaw stops before polling so this is not reported as a webhook cleanup failure. - `setMyCommands failed` with network/fetch errors usually means outbound DNS/HTTPS to `api.telegram.org` is blocked. ### Device pairing commands (`device-pair` plugin) @@ -844,6 +845,14 @@ Per-account, per-group, and per-topic overrides are supported (same inheritance + + + - `getMe returned 401` is a Telegram authentication failure for the configured bot token. + - Re-copy or regenerate the bot token in BotFather, then update `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken`, or `TELEGRAM_BOT_TOKEN` for the default account. + - `deleteWebhook 401 Unauthorized` during startup is also an auth failure; treating it as "no webhook exists" would only defer the same bad-token failure to later API calls. + + + - Node 22+ + custom fetch/proxy can trigger immediate abort behavior if AbortSignal types mismatch. diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index fffe943c47c..aa7d09caf01 100644 --- a/docs/channels/troubleshooting.md +++ b/docs/channels/troubleshooting.md @@ -44,14 +44,15 @@ Full troubleshooting: [WhatsApp troubleshooting](/channels/whatsapp#troubleshoot ### Telegram failure signatures -| Symptom | Fastest check | Fix | -| ----------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | -| `/start` but no usable reply flow | `openclaw pairing list telegram` | Approve pairing or change DM policy. | -| Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot. | -| Send failures with network errors | Inspect logs for Telegram API call failures | Fix DNS/IPv6/proxy routing to `api.telegram.org`. | -| Polling stalls or reconnects slowly | `openclaw logs --follow` for polling diagnostics | Upgrade; if restarts are false positives, tune `pollingStallThresholdMs`. Persistent stalls still point to proxy/DNS/IPv6. | -| `setMyCommands` rejected at startup | Inspect logs for `BOT_COMMANDS_TOO_MUCH` | Reduce plugin/skill/custom Telegram commands or disable native menus. | -| Upgraded and allowlist blocks you | `openclaw security audit` and config allowlists | Run `openclaw doctor --fix` or replace `@username` with numeric sender IDs. | +| Symptom | Fastest check | Fix | +| ------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | +| `/start` but no usable reply flow | `openclaw pairing list telegram` | Approve pairing or change DM policy. | +| Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot. | +| Send failures with network errors | Inspect logs for Telegram API call failures | Fix DNS/IPv6/proxy routing to `api.telegram.org`. | +| Startup reports `getMe returned 401` | Check configured token source | Re-copy or regenerate the BotFather token and update `botToken`, `tokenFile`, or default-account `TELEGRAM_BOT_TOKEN`. | +| Polling stalls or reconnects slowly | `openclaw logs --follow` for polling diagnostics | Upgrade; if restarts are false positives, tune `pollingStallThresholdMs`. Persistent stalls still point to proxy/DNS/IPv6. | +| `setMyCommands` rejected at startup | Inspect logs for `BOT_COMMANDS_TOO_MUCH` | Reduce plugin/skill/custom Telegram commands or disable native menus. | +| Upgraded and allowlist blocks you | `openclaw security audit` and config allowlists | Run `openclaw doctor --fix` or replace `@username` with numeric sender IDs. | Full troubleshooting: [Telegram troubleshooting](/channels/telegram#troubleshooting) diff --git a/extensions/telegram/src/channel.gateway.test.ts b/extensions/telegram/src/channel.gateway.test.ts new file mode 100644 index 00000000000..a70e328882e --- /dev/null +++ b/extensions/telegram/src/channel.gateway.test.ts @@ -0,0 +1,118 @@ +import { + createPluginRuntimeMock, + createStartAccountContext, +} from "openclaw/plugin-sdk/channel-test-helpers"; +import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { telegramPlugin } from "./channel.js"; +import type { TelegramMonitorFn } from "./monitor.types.js"; +import { clearTelegramRuntime, setTelegramRuntime } from "./runtime.js"; +import type { TelegramProbeFn } from "./runtime.types.js"; +import type { TelegramRuntime } from "./runtime.types.js"; + +const probeTelegram = vi.fn(); +const monitorTelegramProvider = vi.fn(); + +function installTelegramRuntime() { + const runtime = createPluginRuntimeMock(); + setTelegramRuntime({ + ...runtime, + channel: { + ...runtime.channel, + telegram: { + probeTelegram: probeTelegram as TelegramProbeFn, + monitorTelegramProvider: monitorTelegramProvider as TelegramMonitorFn, + }, + }, + } as unknown as TelegramRuntime); +} + +function createTelegramConfig(accountId = "default"): OpenClawConfig { + if (accountId === "default") { + return { + channels: { + telegram: { + botToken: "123456:bad-token", + }, + }, + } as OpenClawConfig; + } + + return { + channels: { + telegram: { + accounts: { + [accountId]: { + botToken: "123456:bad-token", + }, + }, + }, + }, + } as OpenClawConfig; +} + +function startTelegramAccount(accountId = "default") { + const cfg = createTelegramConfig(accountId); + const account = telegramPlugin.config.resolveAccount(cfg, accountId); + const startAccount = telegramPlugin.gateway?.startAccount; + expect(startAccount).toBeDefined(); + const ctx = createStartAccountContext({ + account, + cfg, + }); + return { + ctx, + task: startAccount!(ctx), + }; +} + +afterEach(() => { + clearTelegramRuntime(); + probeTelegram.mockReset(); + monitorTelegramProvider.mockReset(); +}); + +describe("telegramPlugin gateway startup", () => { + it("stops before monitor startup when getMe rejects the token", async () => { + installTelegramRuntime(); + probeTelegram.mockResolvedValue({ + ok: false, + status: 401, + error: "Unauthorized", + elapsedMs: 12, + }); + + const { ctx, task } = startTelegramAccount("ops"); + + await expect(task).rejects.toThrow( + 'Telegram bot token unauthorized for account "ops" (getMe returned 401', + ); + await expect(task).rejects.toThrow("channels.telegram.accounts.ops.botToken/tokenFile"); + expect(monitorTelegramProvider).not.toHaveBeenCalled(); + expect(ctx.log?.error).toHaveBeenCalledWith( + expect.stringContaining('Telegram bot token unauthorized for account "ops"'), + ); + }); + + it("keeps existing fallback startup for non-auth probe failures", async () => { + installTelegramRuntime(); + probeTelegram.mockResolvedValue({ + ok: false, + status: 500, + error: "Bad Gateway", + elapsedMs: 12, + }); + monitorTelegramProvider.mockResolvedValue(undefined); + + const { task } = startTelegramAccount(); + + await expect(task).resolves.toBeUndefined(); + expect(monitorTelegramProvider).toHaveBeenCalledWith( + expect.objectContaining({ + token: "123456:bad-token", + accountId: "default", + useWebhook: false, + }), + ); + }); +}); diff --git a/extensions/telegram/src/channel.ts b/extensions/telegram/src/channel.ts index 171211dad0f..4b7474cfb9a 100644 --- a/extensions/telegram/src/channel.ts +++ b/extensions/telegram/src/channel.ts @@ -129,6 +129,16 @@ function resolveTelegramMonitor() { ); } +function formatTelegramUnauthorizedTokenError(account: ResolvedTelegramAccount): string { + const source = + account.tokenSource === "none" ? "no configured token" : `${account.tokenSource} token`; + const credentialPath = + account.accountId === DEFAULT_ACCOUNT_ID + ? "channels.telegram.botToken, channels.telegram.tokenFile, or TELEGRAM_BOT_TOKEN" + : `channels.telegram.accounts.${account.accountId}.botToken/tokenFile`; + return `Telegram bot token unauthorized for account "${account.accountId}" (getMe returned 401 from Telegram; source: ${source}). Update ${credentialPath} with the current BotFather token.`; +} + function getOptionalTelegramRuntime() { try { return getTelegramRuntime(); @@ -880,6 +890,7 @@ export const telegramPlugin = createChatChannelPlugin({ } const token = (account.token ?? "").trim(); let telegramBotLabel = ""; + let unauthorizedTokenReason: string | null = null; try { const probe = await resolveTelegramProbe()(token, 2500, { accountId: account.accountId, @@ -892,11 +903,18 @@ export const telegramPlugin = createChatChannelPlugin({ if (username) { telegramBotLabel = ` (@${username})`; } + if (!probe.ok && probe.status === 401) { + unauthorizedTokenReason = formatTelegramUnauthorizedTokenError(account); + } } catch (err) { if (getTelegramRuntime().logging.shouldLogVerbose()) { ctx.log?.debug?.(`[${account.accountId}] bot probe failed: ${String(err)}`); } } + if (unauthorizedTokenReason) { + ctx.log?.error?.(`[${account.accountId}] ${unauthorizedTokenReason}`); + throw new Error(unauthorizedTokenReason); + } ctx.log?.info(`[${account.accountId}] starting provider${telegramBotLabel}`); const setStatus = createAccountStatusSink({ accountId: account.accountId,