Add Telegram API base and proxy support

Author: Mack Ding

.env.example

@@ -1,4 +1,6 @@
 BOT_TOKEN=123456789:telegram-token-from-botfather
+TELEGRAM_API_BASE=https://api.telegram.org
+TELEGRAM_PROXY_URL=
 TELEGRAM_EXPECTED_USERNAME=
 TELEGRAM_SMOKE_CHAT_ID=
 ALLOWED_USER_IDS=123456789,987654321

README.md

@@ -407,6 +407,8 @@ CODEX_WORKDIR=.
 Common options:
 
 ```bash
+TELEGRAM_API_BASE=https://api.telegram.org
+TELEGRAM_PROXY_URL=
 CODEX_COMMAND=codex
 CODEX_ARGS=
 CODEX_BACKEND=sdk
@@ -537,6 +539,7 @@ Telegram can manage runtime usage of Bot-side MCP and skills, but not install ar
 ## Troubleshooting
 
 - **Bot not responding**: verify `BOT_TOKEN` and `ALLOWED_USER_IDS`
+- **Telegram API blocked**: set `TELEGRAM_PROXY_URL` (HTTP proxy like `http://127.0.0.1:7890`) or run a local Bot API server and set `TELEGRAM_API_BASE`
 - **Codex not producing output**: verify `CODEX_BACKEND`, `CODEX_COMMAND`, and `CODEX_WORKDIR`
 - **SDK backend cannot resume**: verify the host still has access to `~/.codex/sessions` and that the saved thread id belongs to the same working directory
 - **Markdown parse errors**: reduce output size/context; check special characters in tool output

package-lock.json

@@ -47,12 +47,14 @@
     "@octokit/rest": "^22.0.0",
     "@openai/codex-sdk": "^0.114.0",
     "dotenv": "^16.4.7",
+    "https-proxy-agent": "^8.0.0",
     "lodash.throttle": "^4.1.1",
     "node-cron": "^4.0.5",
     "node-pty": "^1.0.0",
     "simple-git": "^3.28.0",
     "strip-ansi": "^7.1.0",
-    "telegraf": "^4.16.3"
+    "telegraf": "^4.16.3",
+    "undici": "^7.24.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",

package.json

@@ -1,5 +1,10 @@
 import "dotenv/config";
 import process from "node:process";
+import {
+  buildTelegramApiUrl,
+  createTelegramFetchDispatcher,
+  normalizeTelegramApiBase
+} from "../src/lib/telegramApi.js";
 
 interface TelegramBotUser {
   id: number;
@@ -28,13 +33,20 @@ const expectedUsername = String(process.env.TELEGRAM_EXPECTED_USERNAME || "")
   .trim()
   .replace(/^@/, "");
 const smokeChatId = String(process.env.TELEGRAM_SMOKE_CHAT_ID || "").trim();
+const apiBase = normalizeTelegramApiBase(process.env.TELEGRAM_API_BASE);
+const dispatcher = createTelegramFetchDispatcher(
+  process.env.TELEGRAM_PROXY_URL
+);
 
 if (!token) {
   console.error("Missing BOT_TOKEN.");
   process.exit(1);
 }
 
-const getMeResponse = await fetch(`https://api.telegram.org/bot${token}/getMe`);
+const getMeResponse = await fetch(
+  buildTelegramApiUrl(apiBase, token, "getMe"),
+  dispatcher ? { dispatcher } : undefined
+);
 const getMePayload =
   (await getMeResponse.json()) as TelegramApiResponse<TelegramBotUser>;
 
@@ -57,7 +69,7 @@ if (expectedUsername && botUser.username !== expectedUsername) {
 if (smokeChatId) {
   const message = `codex-telegram-claws smoke check ${new Date().toISOString()}`;
   const sendResponse = await fetch(
-    `https://api.telegram.org/bot${token}/sendMessage`,
+    buildTelegramApiUrl(apiBase, token, "sendMessage"),
     {
       method: "POST",
       headers: {
@@ -66,7 +78,8 @@ if (smokeChatId) {
       body: JSON.stringify({
         chat_id: smokeChatId,
         text: message
-      })
+      }),
+      ...(dispatcher ? { dispatcher } : {})
     }
   );
   const sendPayload =

scripts/telegramSmoke.ts

@@ -3,6 +3,10 @@ import path from "node:path";
 import process from "node:process";
 import dotenv from "dotenv";
 import { toErrorMessage } from "./lib/errors.js";
+import {
+  normalizeTelegramApiBase,
+  normalizeTelegramProxyUrl
+} from "./lib/telegramApi.js";
 
 dotenv.config();
 
@@ -49,6 +53,8 @@ export interface AppConfig {
   };
   telegram: {
     botToken: string;
+    apiBase: string;
+    proxyUrl?: string;
     allowedUserIds: string[];
     proactiveUserIds: string[];
   };
@@ -374,6 +380,8 @@ export function loadConfig(): AppConfig {
     },
     telegram: {
       botToken: required("BOT_TOKEN"),
+      apiBase: normalizeTelegramApiBase(process.env.TELEGRAM_API_BASE),
+      proxyUrl: normalizeTelegramProxyUrl(process.env.TELEGRAM_PROXY_URL),
       allowedUserIds,
       proactiveUserIds
     },

src/config.ts

@@ -15,10 +15,18 @@ import { ShellManager } from "./runner/shellManager.js";
 import { DevServerManager } from "./runner/devServerManager.js";
 import { Scheduler } from "./cron/scheduler.js";
 import { toErrorMessage } from "./lib/errors.js";
+import { createTelegramApiAgent } from "./lib/telegramApi.js";
 
 const config = loadConfig();
+const telegramApiAgent = createTelegramApiAgent(config.telegram.proxyUrl);
 const bot = new Telegraf(config.telegram.botToken, {
-  handlerTimeout: 120000
+  handlerTimeout: 120000,
+  telegram: {
+    apiRoot: config.telegram.apiBase,
+    ...(telegramApiAgent
+      ? { agent: telegramApiAgent, attachmentAgent: telegramApiAgent }
+      : {})
+  }
 });
 const stateStore = new RuntimeStateStore({ config });
 let mcpClient: McpClient | null = null;

src/index.ts

@@ -0,0 +1,43 @@
+import type { Agent as HttpAgent } from "node:http";
+import type { Dispatcher } from "undici";
+import { ProxyAgent } from "undici";
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+const DEFAULT_TELEGRAM_API_BASE = "https://api.telegram.org";
+
+export function normalizeTelegramApiBase(value?: string): string {
+  const trimmed = String(value || "").trim();
+  if (!trimmed) return DEFAULT_TELEGRAM_API_BASE;
+  return trimmed.replace(/\/+$/, "");
+}
+
+export function normalizeTelegramProxyUrl(value?: string): string | undefined {
+  const trimmed = String(value || "").trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function buildTelegramApiUrl(
+  apiBase: string,
+  token: string,
+  method: string
+): string {
+  const normalized = normalizeTelegramApiBase(apiBase);
+  const baseUrl = new URL(`${normalized}/`);
+  return new URL(`bot${token}/${method}`, baseUrl).toString();
+}
+
+export function createTelegramApiAgent(
+  proxyUrl?: string
+): HttpAgent | undefined {
+  const normalized = normalizeTelegramProxyUrl(proxyUrl);
+  if (!normalized) return undefined;
+  return new HttpsProxyAgent(normalized);
+}
+
+export function createTelegramFetchDispatcher(
+  proxyUrl?: string
+): Dispatcher | undefined {
+  const normalized = normalizeTelegramProxyUrl(proxyUrl);
+  if (!normalized) return undefined;
+  return new ProxyAgent(normalized);
+}

src/lib/telegramApi.ts

@@ -6,6 +6,10 @@ import type { AppConfig } from "../config.js";
 import { repairNodePtySpawnHelperPermissions } from "../runner/ptyPreflight.js";
 import { extractCodexExecResponse } from "../bot/formatter.js";
 import { toErrorMessage } from "../lib/errors.js";
+import {
+  buildTelegramApiUrl,
+  createTelegramFetchDispatcher
+} from "../lib/telegramApi.js";
 
 export type HealthcheckStatus = "pass" | "warn" | "fail";
 
@@ -291,8 +295,17 @@ export async function runHealthcheck(
   const liveTelegramCheck = Boolean(options.telegramLiveCheck);
   if (liveTelegramCheck) {
     try {
+      const url = buildTelegramApiUrl(
+        config.telegram.apiBase,
+        config.telegram.botToken,
+        "getMe"
+      );
+      const dispatcher = createTelegramFetchDispatcher(
+        config.telegram.proxyUrl
+      );
       const response = await fetch(
-        `https://api.telegram.org/bot${config.telegram.botToken}/getMe`
+        url,
+        dispatcher ? { dispatcher } : undefined
       );
       const payload = (await response.json()) as TelegramGetMeResponse;
       if (response.ok && payload?.ok && payload?.result?.username) {

src/ops/healthcheck.ts

@@ -7,6 +7,8 @@ import { loadConfig } from "../src/config.js";
 
 const ENV_KEYS = [
   "BOT_TOKEN",
+  "TELEGRAM_API_BASE",
+  "TELEGRAM_PROXY_URL",
   "ALLOWED_USER_IDS",
   "PROACTIVE_USER_IDS",
   "STATE_FILE",
@@ -95,6 +97,8 @@ test("loadConfig parses env values into runtime config", () => {
   const config = withEnv(
     {
       BOT_TOKEN: "telegram-token",
+      TELEGRAM_API_BASE: "https://telegram.example/api/",
+      TELEGRAM_PROXY_URL: "http://127.0.0.1:7890",
       ALLOWED_USER_IDS: "1, 2",
       PROACTIVE_USER_IDS: "2",
       STATE_FILE: stateFile,
@@ -134,6 +138,8 @@ test("loadConfig parses env values into runtime config", () => {
   );
 
   assert.equal(config.telegram.botToken, "telegram-token");
+  assert.equal(config.telegram.apiBase, "https://telegram.example/api");
+  assert.equal(config.telegram.proxyUrl, "http://127.0.0.1:7890");
   assert.equal(config.app.stateFile, stateFile);
   assert.deepEqual(config.telegram.allowedUserIds, ["1", "2"]);
   assert.deepEqual(config.telegram.proactiveUserIds, ["2"]);