Telegram: add webhookCertPath and skip stale-socket in webhook mode (#39303)

fellanH · fellanH · commit b798609e1e52 · 2026-03-08T02:00:01.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -231,6 +231,8 @@ Docs: https://docs.openclaw.ai
 - Daemon/systemd fresh-install probe: check for OpenClaw's managed user unit before running `systemctl --user is-enabled`, so first-time Linux installs no longer fail on generic missing-unit probe errors. (#38819) Thanks @adaHubble.
 - Gateway/Windows restart supervision: relaunch task-managed gateways through Scheduled Task with quoted helper-script command paths, distinguish restart-capable supervisors per platform, and stop orphaned Windows gateway children during self-restart. (#38825) Thanks @obviyus.
 - Telegram/native topic command routing: resolve forum-topic native commands through the same conversation route as inbound messages so topic `agentId` overrides and bound topic sessions target the active session instead of the default topic-parent session. (#38871) Thanks @obviyus.
+- Gateway/Telegram webhook certificate: add `webhookCertPath` configuration option to allow uploading self-signed certificates during webhook registration, preventing SSL verification failures after health-monitor restarts. Fixes #39303.
+- Gateway/Health monitor webhook mode: skip `stale-socket` detection for any channel operating in webhook mode, as there is no persistent outgoing socket to go stale. Fixes #39303.
 
 ## 2026.3.2
 
diff --git a/extensions/telegram/src/channel.ts b/extensions/telegram/src/channel.ts
@@ -506,6 +506,7 @@ export const telegramPlugin: ChannelPlugin<ResolvedTelegramAccount, TelegramProb
         webhookPath: account.config.webhookPath,
         webhookHost: account.config.webhookHost,
         webhookPort: account.config.webhookPort,
+        webhookCertPath: account.config.webhookCertPath,
       });
     },
     logoutAccount: async ({ accountId, cfg }) => {
diff --git a/src/config/types.telegram.ts b/src/config/types.telegram.ts
@@ -140,6 +140,8 @@ export type TelegramAccountConfig = {
   webhookHost?: string;
   /** Local webhook listener bind port (default: 8787). */
   webhookPort?: number;
+  /** Path to the self-signed certificate (PEM) to upload to Telegram during webhook registration. */
+  webhookCertPath?: string;
   /** Per-action tool gating (default: true for all). */
   actions?: TelegramActionConfig;
   /** Telegram thread/conversation binding overrides. */
diff --git a/src/config/zod-schema.providers-core.ts b/src/config/zod-schema.providers-core.ts
@@ -221,6 +221,12 @@ export const TelegramAccountSchemaBase = z
       .describe(
         "Local bind port for the webhook listener. Defaults to 8787; set to 0 to let the OS assign an ephemeral port.",
       ),
+    webhookCertPath: z
+      .string()
+      .optional()
+      .describe(
+        "Path to the self-signed certificate (PEM) to upload to Telegram during webhook registration. Required for self-signed certs (direct IP or no domain).",
+      ),
     actions: z
       .object({
         reactions: z.boolean().optional(),
diff --git a/src/gateway/channel-health-policy.test.ts b/src/gateway/channel-health-policy.test.ts
@@ -143,6 +143,27 @@ describe("evaluateChannelHealth", () => {
     expect(evaluation).toEqual({ healthy: true, reason: "healthy" });
   });
 
+  it("skips stale-socket detection for channels in webhook mode", () => {
+    const evaluation = evaluateChannelHealth(
+      {
+        running: true,
+        connected: true,
+        enabled: true,
+        configured: true,
+        lastStartAt: 0,
+        lastEventAt: 0,
+        mode: "webhook",
+      },
+      {
+        channelId: "discord",
+        now: 100_000,
+        channelConnectGraceMs: 10_000,
+        staleEventThresholdMs: 30_000,
+      },
+    );
+    expect(evaluation).toEqual({ healthy: true, reason: "healthy" });
+  });
+
   it("does not flag stale sockets for channels without event tracking", () => {
     const evaluation = evaluateChannelHealth(
       {
diff --git a/src/gateway/channel-health-policy.ts b/src/gateway/channel-health-policy.ts
@@ -12,6 +12,7 @@ export type ChannelHealthSnapshot = {
   lastEventAt?: number | null;
   lastStartAt?: number | null;
   reconnectAttempts?: number;
+  mode?: string;
 };
 
 export type ChannelHealthEvaluationReason =
@@ -100,11 +101,13 @@ export function evaluateChannelHealth(
   if (snapshot.connected === false) {
     return { healthy: false, reason: "disconnected" };
   }
-  // Skip stale-socket check for Telegram (long-polling mode). Each polling request
-  // acts as a heartbeat, so the half-dead WebSocket scenario this check is designed
-  // to catch does not apply to Telegram's long-polling architecture.
+  // Skip stale-socket check for Telegram (long-polling mode) and any channel
+  // explicitly operating in webhook mode. In these cases, there is no persistent
+  // outgoing socket that can go half-dead, so the lack of incoming events
+  // does not necessarily indicate a connection failure.
   if (
     policy.channelId !== "telegram" &&
+    snapshot.mode !== "webhook" &&
     snapshot.connected === true &&
     snapshot.lastEventAt != null
   ) {
diff --git a/src/telegram/monitor.ts b/src/telegram/monitor.ts
@@ -30,6 +30,7 @@ export type MonitorTelegramOpts = {
   webhookHost?: string;
   proxyFetch?: typeof fetch;
   webhookUrl?: string;
+  webhookCertPath?: string;
 };
 
 export function createTelegramRunnerOptions(cfg: OpenClawConfig): RunOptions<unknown> {
@@ -172,6 +173,7 @@ export async function monitorTelegramProvider(opts: MonitorTelegramOpts = {}) {
         fetch: proxyFetch,
         abortSignal: opts.abortSignal,
         publicUrl: opts.webhookUrl,
+        webhookCertPath: opts.webhookCertPath,
       });
       await waitForAbortSignal(opts.abortSignal);
       return;
diff --git a/src/telegram/webhook.test.ts b/src/telegram/webhook.test.ts
@@ -353,6 +353,27 @@ describe("startTelegramWebhook", () => {
     );
   });
 
+  it("registers webhook with certificate when webhookCertPath is provided", async () => {
+    setWebhookSpy.mockClear();
+    await withStartedWebhook(
+      {
+        secret: TELEGRAM_SECRET,
+        path: TELEGRAM_WEBHOOK_PATH,
+        webhookCertPath: "/path/to/cert.pem",
+      },
+      async () => {
+        expect(setWebhookSpy).toHaveBeenCalledWith(
+          expect.any(String),
+          expect.objectContaining({
+            certificate: expect.objectContaining({
+              fileData: "/path/to/cert.pem",
+            }),
+          }),
+        );
+      },
+    );
+  });
+
   it("invokes webhook handler on matching path", async () => {
     handlerSpy.mockClear();
     createTelegramBotSpy.mockClear();
diff --git a/src/telegram/webhook.ts b/src/telegram/webhook.ts
@@ -1,5 +1,5 @@
 import { createServer } from "node:http";
-import { webhookCallback } from "grammy";
+import { InputFile, webhookCallback } from "grammy";
 import type { OpenClawConfig } from "../config/config.js";
 import { isDiagnosticsEnabled } from "../infra/diagnostic-events.js";
 import { formatErrorMessage } from "../infra/errors.js";
@@ -87,6 +87,7 @@ export async function startTelegramWebhook(opts: {
   abortSignal?: AbortSignal;
   healthPath?: string;
   publicUrl?: string;
+  webhookCertPath?: string;
 }) {
   const path = opts.path ?? "/telegram-webhook";
   const healthPath = opts.healthPath ?? "/healthz";
@@ -241,6 +242,7 @@ export async function startTelegramWebhook(opts: {
         bot.api.setWebhook(publicUrl, {
           secret_token: secret,
           allowed_updates: resolveTelegramAllowedUpdates(),
+          certificate: opts.webhookCertPath ? new InputFile(opts.webhookCertPath) : undefined,
         }),
     });
   } catch (err) {
