feat: /telegram backend load

src/commands.ts

@@ -43,6 +43,7 @@ import share from './commands/share/index.js'
 import skills from './commands/skills/index.js'
 import status from './commands/status/index.js'
 import tasks from './commands/tasks/index.js'
+import telegram from './commands/telegram/index.js'
 import teleport from './commands/teleport/index.js'
 /* eslint-disable @typescript-eslint/no-require-imports */
 const agentsPlatform =
@@ -302,6 +303,7 @@ const COMMANDS = memoize((): Command[] => [
   statusline,
   stickers,
   tag,
+  telegram,
   theme,
   feedback,
   review,

src/commands/telegram/index.ts

@@ -0,0 +1,10 @@
+import type { Command } from '../../commands.js'
+
+const telegram = {
+  type: 'local-jsx',
+  name: 'telegram',
+  description: 'Connect a Telegram bot to this session',
+  load: () => import('./telegram.js'),
+} satisfies Command
+
+export default telegram

src/commands/telegram/telegram.tsx

@@ -0,0 +1,432 @@
+import * as React from 'react'
+import { Box, Text, useInput } from '../../ink.js'
+import { Dialog } from '../../components/design-system/Dialog.js'
+import { ListItem } from '../../components/design-system/ListItem.js'
+import type { LocalJSXCommandContext } from '../../commands.js'
+import type { LocalJSXCommandOnDone } from '../../types/command.js'
+import { telegramService } from '../../services/telegram/TelegramService.js'
+import {
+  clearTelegramConfig,
+  formatAllowedTelegramUserIds,
+  getTelegramConfig,
+  maskTelegramToken,
+  parseAllowedTelegramUserIds,
+  saveTelegramConfig,
+} from '../../services/telegram/telegramConfig.js'
+
+type Step =
+  | { type: 'menu' }
+  | { type: 'edit-token' }
+  | { type: 'edit-user-ids' }
+  | { type: 'confirm-clear' }
+
+type Notice = {
+  text: string
+  tone: 'success' | 'error' | 'info'
+}
+
+function TextInput({
+  title,
+  hint,
+  initialValue,
+  masked = false,
+  onSubmit,
+  onCancel,
+}: {
+  title: string
+  hint: string
+  initialValue?: string
+  masked?: boolean
+  onSubmit: (value: string) => void
+  onCancel: () => void
+}) {
+  const [value, setValue] = React.useState(initialValue ?? '')
+  const [cursorOffset, setCursorOffset] = React.useState(
+    (initialValue ?? '').length,
+  )
+
+  useInput((input, key) => {
+    if (key.escape) {
+      onCancel()
+      return
+    }
+
+    if (key.return) {
+      onSubmit(value.trim())
+      return
+    }
+
+    if (key.leftArrow) {
+      setCursorOffset(current => Math.max(0, current - 1))
+      return
+    }
+
+    if (key.rightArrow) {
+      setCursorOffset(current => Math.min(value.length, current + 1))
+      return
+    }
+
+    if (key.backspace || key.delete) {
+      if (cursorOffset === 0) return
+      const nextValue =
+        value.slice(0, cursorOffset - 1) + value.slice(cursorOffset)
+      setValue(nextValue)
+      setCursorOffset(current => Math.max(0, current - 1))
+      return
+    }
+
+    if (input) {
+      const nextValue =
+        value.slice(0, cursorOffset) + input + value.slice(cursorOffset)
+      setValue(nextValue)
+      setCursorOffset(current => current + input.length)
+    }
+  })
+
+  const displayValue = masked ? '*'.repeat(value.length) : value
+  const cursorChar =
+    cursorOffset < displayValue.length ? displayValue[cursorOffset] : ' '
+
+  return (
+    <Box flexDirection="column" gap={1}>
+      <Text bold>{title}</Text>
+      <Text dimColor>{hint}</Text>
+      <Box flexDirection="column" marginTop={1}>
+        <Text dimColor>Value:</Text>
+        <Box>
+          <Text>{displayValue.slice(0, cursorOffset)}</Text>
+          <Text backgroundColor="white" color="black">
+            {cursorChar}
+          </Text>
+          <Text>{displayValue.slice(cursorOffset + 1)}</Text>
+        </Box>
+      </Box>
+      <Text dimColor>[Enter] 保存 · [Esc] 返回</Text>
+    </Box>
+  )
+}
+
+function ConfirmClear({
+  onConfirm,
+  onCancel,
+}: {
+  onConfirm: () => void
+  onCancel: () => void
+}) {
+  useInput((_, key) => {
+    if (key.escape) {
+      onCancel()
+      return
+    }
+
+    if (key.return) {
+      onConfirm()
+    }
+  })
+
+  return (
+    <Box flexDirection="column" gap={1}>
+      <Text color="yellow">这会清空 Telegram Bot Token 和 user id 白名单。</Text>
+      <Text dimColor>
+        如果当前 bot 正在运行，会一并停止。按 Enter 确认，Esc 返回。
+      </Text>
+    </Box>
+  )
+}
+
+function TelegramDialog({
+  onDone,
+}: {
+  onDone: LocalJSXCommandOnDone
+}) {
+  const serviceState = React.useSyncExternalStore(
+    telegramService.subscribe,
+    telegramService.getStateSnapshot,
+  )
+  const [config, setConfig] = React.useState(() => getTelegramConfig())
+  const [step, setStep] = React.useState<Step>({ type: 'menu' })
+  const [notice, setNotice] = React.useState<Notice | null>(null)
+  const [focusIndex, setFocusIndex] = React.useState(0)
+  const [busy, setBusy] = React.useState(false)
+
+  const menuItems = React.useMemo(
+    () => [
+      {
+        label: '设置 Bot Token',
+        action: () => setStep({ type: 'edit-token' }),
+      },
+      {
+        label: '设置允许访问的 Telegram user id',
+        action: () => setStep({ type: 'edit-user-ids' }),
+      },
+      {
+        label:
+          serviceState.status === 'running' ? '停止当前 Telegram Bot' : '启动当前 Telegram Bot',
+        action: async () => {
+          setBusy(true)
+          try {
+            if (serviceState.status === 'running') {
+              await telegramService.stop()
+              setNotice({ text: 'Telegram Bot 已停止。', tone: 'success' })
+            } else {
+              await telegramService.startFromSavedConfig()
+              setNotice({
+                text: 'Telegram Bot 已启动，可以在 Telegram 私聊中发送消息。',
+                tone: 'success',
+              })
+            }
+          } catch (error) {
+            setNotice({
+              text: error instanceof Error ? error.message : '启动 Telegram Bot 失败',
+              tone: 'error',
+            })
+          } finally {
+            setBusy(false)
+          }
+        },
+      },
+      {
+        label: '清空 Telegram 配置',
+        action: () => setStep({ type: 'confirm-clear' }),
+      },
+      {
+        label: '关闭',
+        action: () => onDone(undefined, { display: 'skip' }),
+      },
+    ],
+    [onDone, serviceState.status],
+  )
+
+  React.useEffect(() => {
+    setFocusIndex(current => Math.min(current, menuItems.length - 1))
+  }, [menuItems.length])
+
+  const refreshConfig = React.useCallback(() => {
+    setConfig(getTelegramConfig())
+  }, [])
+
+  const maybeRestartService = React.useCallback(async () => {
+    if (serviceState.status !== 'running') return
+    await telegramService.restartFromSavedConfig()
+  }, [serviceState.status])
+
+  const saveToken = React.useCallback(
+    async (value: string) => {
+      if (!value) {
+        setNotice({ text: 'Bot Token 不能为空。', tone: 'error' })
+        setStep({ type: 'menu' })
+        return
+      }
+
+      setBusy(true)
+      try {
+        saveTelegramConfig({ botToken: value })
+        refreshConfig()
+        await maybeRestartService()
+        setNotice({ text: 'Bot Token 已保存。', tone: 'success' })
+      } catch (error) {
+        setNotice({
+          text: error instanceof Error ? error.message : '保存 Bot Token 失败',
+          tone: 'error',
+        })
+      } finally {
+        setBusy(false)
+        setStep({ type: 'menu' })
+      }
+    },
+    [maybeRestartService, refreshConfig],
+  )
+
+  const saveUserIds = React.useCallback(
+    async (value: string) => {
+      const userIds = parseAllowedTelegramUserIds(value)
+      if (userIds.length === 0) {
+        setNotice({
+          text: '至少需要一个有效的 Telegram user id。',
+          tone: 'error',
+        })
+        setStep({ type: 'menu' })
+        return
+      }
+
+      setBusy(true)
+      try {
+        saveTelegramConfig({ allowedUserIds: userIds })
+        refreshConfig()
+        await maybeRestartService()
+        setNotice({ text: 'Telegram user id 白名单已保存。', tone: 'success' })
+      } catch (error) {
+        setNotice({
+          text: error instanceof Error ? error.message : '保存 Telegram user id 失败',
+          tone: 'error',
+        })
+      } finally {
+        setBusy(false)
+        setStep({ type: 'menu' })
+      }
+    },
+    [maybeRestartService, refreshConfig],
+  )
+
+  const clearConfigAndStop = React.useCallback(async () => {
+    setBusy(true)
+    try {
+      await telegramService.stop()
+      clearTelegramConfig()
+      refreshConfig()
+      setNotice({ text: 'Telegram 配置已清空。', tone: 'success' })
+    } catch (error) {
+      setNotice({
+        text: error instanceof Error ? error.message : '清空 Telegram 配置失败',
+        tone: 'error',
+      })
+    } finally {
+      setBusy(false)
+      setStep({ type: 'menu' })
+    }
+  }, [refreshConfig])
+
+  useInput((_, key) => {
+    if (step.type !== 'menu' || busy) return
+
+    if (key.escape) {
+      onDone(undefined, { display: 'skip' })
+      return
+    }
+
+    if (key.upArrow) {
+      setFocusIndex(current => (current - 1 + menuItems.length) % menuItems.length)
+      return
+    }
+
+    if (key.downArrow) {
+      setFocusIndex(current => (current + 1) % menuItems.length)
+      return
+    }
+
+    if (key.return) {
+      void menuItems[focusIndex]?.action()
+    }
+  })
+
+  const noticeColor =
+    notice?.tone === 'error'
+      ? 'red'
+      : notice?.tone === 'success'
+        ? 'green'
+        : 'cyan'
+
+  if (step.type === 'edit-token') {
+    return (
+      <Dialog title="Telegram Bot Token" onCancel={() => setStep({ type: 'menu' })}>
+        <TextInput
+          title="Bot Token"
+          hint="从 BotFather 获取 token。保存后，如当前 bot 正在运行会自动重启。"
+          initialValue={config?.botToken}
+          masked={true}
+          onSubmit={value => {
+            void saveToken(value)
+          }}
+          onCancel={() => setStep({ type: 'menu' })}
+        />
+      </Dialog>
+    )
+  }
+
+  if (step.type === 'edit-user-ids') {
+    return (
+      <Dialog
+        title="Telegram User IDs"
+        onCancel={() => setStep({ type: 'menu' })}
+      >
+        <TextInput
+          title="允许访问的 Telegram user id"
+          hint="可输入一个或多个 user id，支持空格或逗号分隔。可通过 @userinfobot 查询。"
+          initialValue={formatAllowedTelegramUserIds(config?.allowedUserIds)}
+          onSubmit={value => {
+            void saveUserIds(value)
+          }}
+          onCancel={() => setStep({ type: 'menu' })}
+        />
+      </Dialog>
+    )
+  }
+
+  if (step.type === 'confirm-clear') {
+    return (
+      <Dialog title="Clear Telegram Config" onCancel={() => setStep({ type: 'menu' })}>
+        <ConfirmClear
+          onConfirm={() => {
+            void clearConfigAndStop()
+          }}
+          onCancel={() => setStep({ type: 'menu' })}
+        />
+      </Dialog>
+    )
+  }
+
+  return (
+    <Dialog title="Telegram" onCancel={() => onDone(undefined, { display: 'skip' })}>
+      <Box flexDirection="column" gap={1}>
+        <Text dimColor>
+          在当前 VersperClaw 进程内启动 Telegram 长轮询，并把私聊消息接入当前会话。
+        </Text>
+        <Text>
+          状态:
+          {' '}
+          <Text color={serviceState.status === 'running' ? 'green' : 'yellow'}>
+            {serviceState.status === 'running'
+              ? '运行中'
+              : serviceState.status === 'starting'
+                ? '启动中'
+                : '未启动'}
+          </Text>
+        </Text>
+        <Text>Bot Token: {maskTelegramToken(config?.botToken)}</Text>
+        <Text>
+          允许 user id:
+          {' '}
+          {config?.allowedUserIds?.length
+            ? config.allowedUserIds.join(', ')
+            : '未配置'}
+        </Text>
+        <Text>
+          当前 bot:
+          {' '}
+          {serviceState.botUsername
+            ? `@${serviceState.botUsername}`
+            : '尚未连接 Telegram'}
+        </Text>
+        <Text>
+          最近会话:
+          {' '}
+          {serviceState.activeUserId && serviceState.activeChatId
+            ? `user ${serviceState.activeUserId} / chat ${serviceState.activeChatId}`
+            : '暂无'}
+        </Text>
+        {serviceState.lastError ? (
+          <Text color="red">最近错误: {serviceState.lastError}</Text>
+        ) : null}
+        {notice ? <Text color={noticeColor}>{notice.text}</Text> : null}
+        {busy ? <Text dimColor>处理中，请稍候...</Text> : null}
+        <Box flexDirection="column" marginTop={1}>
+          {menuItems.map((item, index) => (
+            <ListItem key={item.label} isFocused={focusIndex === index}>
+              <Text>{item.label}</Text>
+            </ListItem>
+          ))}
+        </Box>
+        <Text dimColor>上下箭头选择，Enter 执行，Esc 关闭</Text>
+      </Box>
+    </Dialog>
+  )
+}
+
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  _context: LocalJSXCommandContext,
+): Promise<React.ReactNode> {
+  return <TelegramDialog onDone={onDone} />
+}
+
+export default call

src/hooks/useTelegramBridge.ts

@@ -0,0 +1,97 @@
+import { useEffect, useRef } from 'react'
+import { telegramService } from '../services/telegram/TelegramService.js'
+import {
+  TELEGRAM_CHANNEL_SERVER,
+  type TelegramInboundEvent,
+} from '../services/telegram/telegramTypes.js'
+import type { Message } from '../types/message.js'
+import { enqueue } from '../utils/messageQueueManager.js'
+import { getContentText } from '../utils/messages.js'
+import { logForDebugging } from '../utils/debug.js'
+
+type Props = {
+  messages: Message[]
+  isLoading: boolean
+}
+
+type ActiveTelegramTurn = {
+  chatId: string
+  lastAssistantText?: string
+}
+
+export function useTelegramBridge({ messages, isLoading }: Props): void {
+  const pendingInboundRef = useRef<TelegramInboundEvent[]>([])
+  const activeTurnRef = useRef<ActiveTelegramTurn | null>(null)
+  const lastProcessedMessageCountRef = useRef(messages.length)
+  const previousLoadingRef = useRef(isLoading)
+
+  useEffect(() => {
+    return telegramService.subscribeToInbound(event => {
+      pendingInboundRef.current.push(event)
+      enqueue({
+        value: event.text,
+        mode: 'prompt',
+        skipSlashCommands: true,
+        origin: {
+          kind: 'channel',
+          server: TELEGRAM_CHANNEL_SERVER,
+        } as const,
+      })
+    })
+  }, [])
+
+  useEffect(() => {
+    const newMessages = messages.slice(lastProcessedMessageCountRef.current)
+
+    for (const message of newMessages) {
+      if (
+        message.type === 'user' &&
+        message.origin?.kind === 'channel' &&
+        message.origin.server === TELEGRAM_CHANNEL_SERVER
+      ) {
+        const inbound = pendingInboundRef.current.shift()
+        if (inbound) {
+          activeTurnRef.current = {
+            chatId: inbound.chatId,
+          }
+        }
+        continue
+      }
+
+      if (message.type === 'assistant' && activeTurnRef.current) {
+        const text = getContentText(message.message.content)
+        if (text) {
+          activeTurnRef.current.lastAssistantText = text
+        }
+      }
+    }
+
+    lastProcessedMessageCountRef.current = messages.length
+  }, [messages])
+
+  useEffect(() => {
+    const wasLoading = previousLoadingRef.current
+    previousLoadingRef.current = isLoading
+
+    if (!wasLoading || isLoading || !activeTurnRef.current) {
+      return
+    }
+
+    const { chatId, lastAssistantText } = activeTurnRef.current
+    activeTurnRef.current = null
+
+    void telegramService
+      .sendMessage(
+        chatId,
+        lastAssistantText ?? '这一轮没有可回传的文本结果，请查看本地终端会话。',
+      )
+      .catch(error => {
+        logForDebugging(
+          `[telegram] failed to send outbound reply: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+          { level: 'error' },
+        )
+      })
+  }, [isLoading])
+}

src/screens/REPL.tsx

@@ -141,6 +141,7 @@ import { gracefulShutdownSync } from '../utils/gracefulShutdown.js';
 import { handlePromptSubmit, type PromptInputHelpers } from '../utils/handlePromptSubmit.js';
 import { useQueueProcessor } from '../hooks/useQueueProcessor.js';
 import { useMailboxBridge } from '../hooks/useMailboxBridge.js';
+import { useTelegramBridge } from '../hooks/useTelegramBridge.js';
 import { queryCheckpoint, logQueryProfileReport } from '../utils/queryProfiler.js';
 import type { Message as MessageType, UserMessage, ProgressMessage, HookResultMessage, PartialCompactDirection } from '../types/message.js';
 import { query } from '../query.js';

src/services/telegram/TelegramService.ts

@@ -0,0 +1,330 @@
+import { logForDebugging } from '../../utils/debug.js'
+import { getTelegramRuntimeConfig } from './telegramConfig.js'
+import type {
+  TelegramGetMeResponse,
+  TelegramGetUpdatesResponse,
+  TelegramInboundEvent,
+  TelegramRuntimeConfig,
+  TelegramSendMessageResponse,
+  TelegramServiceState,
+  TelegramUpdate,
+} from './telegramTypes.js'
+
+type Listener = () => void
+type InboundListener = (event: TelegramInboundEvent) => void
+
+const TELEGRAM_API_BASE = 'https://api.telegram.org'
+const MAX_TELEGRAM_MESSAGE_LENGTH = 4000
+const POLL_TIMEOUT_SECONDS = 25
+const RETRY_DELAY_MS = 3000
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function normalizeTelegramError(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}
+
+function chunkTelegramMessage(text: string): string[] {
+  const normalized = text.trim()
+  if (!normalized) return ['模型本轮没有返回可发送的文本结果。']
+
+  const chunks: string[] = []
+  for (let i = 0; i < normalized.length; i += MAX_TELEGRAM_MESSAGE_LENGTH) {
+    chunks.push(normalized.slice(i, i + MAX_TELEGRAM_MESSAGE_LENGTH))
+  }
+  return chunks
+}
+
+function hasSameConfig(
+  left: TelegramRuntimeConfig | undefined,
+  right: TelegramRuntimeConfig,
+): boolean {
+  if (!left) return false
+  return (
+    left.botToken === right.botToken &&
+    left.allowedUserIds.join(',') === right.allowedUserIds.join(',')
+  )
+}
+
+class TelegramService {
+  private listeners = new Set<Listener>()
+  private inboundListeners = new Set<InboundListener>()
+  private state: TelegramServiceState = { status: 'stopped' }
+  private config?: TelegramRuntimeConfig
+  private abortController: AbortController | null = null
+  private runId = 0
+  private nextUpdateOffset: number | undefined
+
+  subscribe = (listener: Listener): (() => void) => {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  subscribeToInbound = (listener: InboundListener): (() => void) => {
+    this.inboundListeners.add(listener)
+    return () => {
+      this.inboundListeners.delete(listener)
+    }
+  }
+
+  getStateSnapshot = (): TelegramServiceState => this.state
+
+  async start(config: TelegramRuntimeConfig): Promise<void> {
+    if (this.state.status === 'running' && hasSameConfig(this.config, config)) {
+      return
+    }
+
+    await this.stop()
+
+    const runId = ++this.runId
+    const abortController = new AbortController()
+    this.abortController = abortController
+    this.config = config
+    this.nextUpdateOffset = undefined
+
+    this.setState({
+      status: 'starting',
+      lastError: undefined,
+      botUsername: undefined,
+      botDisplayName: undefined,
+      startedAt: undefined,
+      activeChatId: undefined,
+      activeUserId: undefined,
+    })
+
+    try {
+      const response = await this.callTelegram<TelegramGetMeResponse>(
+        config,
+        'getMe',
+        {},
+        abortController.signal,
+      )
+
+      if (runId !== this.runId || abortController.signal.aborted) return
+
+      this.setState({
+        status: 'running',
+        botUsername: response.result?.username,
+        botDisplayName: response.result?.first_name,
+        startedAt: new Date().toISOString(),
+        lastError: undefined,
+      })
+
+      logForDebugging(
+        `[telegram] connected as @${response.result?.username ?? 'unknown'}`,
+      )
+
+      void this.pollLoop(runId, config, abortController.signal)
+    } catch (error) {
+      if (abortController.signal.aborted || runId !== this.runId) return
+      const message = normalizeTelegramError(error)
+      this.setState({
+        status: 'stopped',
+        lastError: message,
+      })
+      throw error
+    }
+  }
+
+  async startFromSavedConfig(): Promise<void> {
+    await this.start(getTelegramRuntimeConfig())
+  }
+
+  async restartFromSavedConfig(): Promise<void> {
+    await this.startFromSavedConfig()
+  }
+
+  async stop(): Promise<void> {
+    this.runId++
+    this.abortController?.abort()
+    this.abortController = null
+    this.config = undefined
+    this.nextUpdateOffset = undefined
+
+    if (this.state.status !== 'stopped') {
+      this.setState({
+        ...this.state,
+        status: 'stopped',
+        startedAt: undefined,
+      })
+    }
+  }
+
+  async sendMessage(chatId: string, text: string): Promise<void> {
+    if (!this.config) {
+      throw new Error('Telegram service is not running')
+    }
+
+    for (const chunk of chunkTelegramMessage(text)) {
+      await this.callTelegram<TelegramSendMessageResponse>(
+        this.config,
+        'sendMessage',
+        {
+          chat_id: Number(chatId),
+          text: chunk,
+        },
+      )
+    }
+  }
+
+  private setState(nextState: TelegramServiceState): void {
+    this.state = nextState
+    for (const listener of this.listeners) {
+      listener()
+    }
+  }
+
+  private patchState(patch: Partial<TelegramServiceState>): void {
+    this.setState({
+      ...this.state,
+      ...patch,
+    })
+  }
+
+  private emitInbound(event: TelegramInboundEvent): void {
+    for (const listener of this.inboundListeners) {
+      listener(event)
+    }
+  }
+
+  private async pollLoop(
+    runId: number,
+    config: TelegramRuntimeConfig,
+    signal: AbortSignal,
+  ): Promise<void> {
+    while (!signal.aborted && runId === this.runId) {
+      try {
+        const response = await this.callTelegram<TelegramGetUpdatesResponse>(
+          config,
+          'getUpdates',
+          {
+            offset: this.nextUpdateOffset,
+            timeout: POLL_TIMEOUT_SECONDS,
+            allowed_updates: ['message'],
+          },
+          signal,
+        )
+
+        if (signal.aborted || runId !== this.runId) return
+
+        if (this.state.lastError) {
+          this.patchState({ lastError: undefined })
+        }
+
+        for (const update of response.result ?? []) {
+          this.handleUpdate(update, config)
+        }
+      } catch (error) {
+        if (signal.aborted || runId !== this.runId) return
+
+        const message = normalizeTelegramError(error)
+        logForDebugging(`[telegram] polling failed: ${message}`, {
+          level: 'error',
+        })
+        this.patchState({ lastError: message })
+        await sleep(RETRY_DELAY_MS)
+      }
+    }
+  }
+
+  private handleUpdate(
+    update: TelegramUpdate,
+    config: TelegramRuntimeConfig,
+  ): void {
+    this.nextUpdateOffset = update.update_id + 1
+
+    const message = update.message
+    const chatId = message?.chat?.id
+    const userId = message?.from?.id
+
+    if (!message || chatId === undefined || userId === undefined) return
+    if (message.from?.is_bot) return
+    if (message.chat?.type !== 'private') return
+
+    const normalizedChatId = String(chatId)
+    const normalizedUserId = String(userId)
+
+    if (!config.allowedUserIds.includes(normalizedUserId)) {
+      void this.sendMessage(
+        normalizedChatId,
+        '这个 Telegram user id 尚未被当前 /telegram 配置授权。',
+      ).catch(() => {})
+      return
+    }
+
+    this.patchState({
+      activeChatId: normalizedChatId,
+      activeUserId: normalizedUserId,
+    })
+
+    const text = message.text?.trim()
+
+    if (!text) {
+      void this.sendMessage(
+        normalizedChatId,
+        '当前只支持文本消息，请发送纯文本内容。',
+      ).catch(() => {})
+      return
+    }
+
+    if (text === '/start') {
+      void this.sendMessage(
+        normalizedChatId,
+        'Telegram 已连接到当前 VersperClaw 会话。直接发送文本即可开始远程对话。',
+      ).catch(() => {})
+      return
+    }
+
+    this.emitInbound({
+      kind: 'inbound-message',
+      chatId: normalizedChatId,
+      userId: normalizedUserId,
+      text,
+      messageId: message.message_id,
+      updateId: update.update_id,
+    })
+  }
+
+  private async callTelegram<T>(
+    config: TelegramRuntimeConfig,
+    method: string,
+    payload: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const response = await fetch(
+      `${TELEGRAM_API_BASE}/bot${config.botToken}/${method}`,
+      {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(payload),
+        signal,
+      },
+    )
+
+    if (!response.ok) {
+      throw new Error(`Telegram API ${method} failed with HTTP ${response.status}`)
+    }
+
+    const json = await response.json() as {
+      ok?: boolean
+      description?: string
+    }
+
+    if (!json.ok) {
+      throw new Error(
+        `Telegram API ${method} failed: ${json.description ?? 'unknown error'}`,
+      )
+    }
+
+    return json as T
+  }
+}
+
+export const telegramService = new TelegramService()

src/services/telegram/telegramConfig.ts

@@ -0,0 +1,71 @@
+import {
+  getGlobalConfig,
+  saveGlobalConfig,
+  type TelegramConfig,
+} from '../../utils/config.js'
+import type {
+  TelegramConfigDraft,
+  TelegramRuntimeConfig,
+} from './telegramTypes.js'
+
+export function getTelegramConfig(): TelegramConfig | undefined {
+  return getGlobalConfig().telegram
+}
+
+export function saveTelegramConfig(updates: TelegramConfigDraft): void {
+  saveGlobalConfig(current => ({
+    ...current,
+    telegram: {
+      ...(current.telegram ?? {}),
+      ...updates,
+      updatedAt: new Date().toISOString(),
+    },
+  }))
+}
+
+export function clearTelegramConfig(): void {
+  saveGlobalConfig(current => ({
+    ...current,
+    telegram: undefined,
+  }))
+}
+
+export function maskTelegramToken(token?: string): string {
+  if (!token) return '未配置'
+  if (token.length <= 12) return `${token.slice(0, 4)}...`
+  return `${token.slice(0, 8)}...${token.slice(-4)}`
+}
+
+export function parseAllowedTelegramUserIds(raw: string): string[] {
+  return [...new Set(
+    raw
+      .split(/[\s,]+/)
+      .map(part => part.trim())
+      .filter(Boolean)
+      .filter(part => /^\d+$/.test(part)),
+  )]
+}
+
+export function formatAllowedTelegramUserIds(userIds?: string[]): string {
+  if (!userIds || userIds.length === 0) return ''
+  return userIds.join(', ')
+}
+
+export function getTelegramRuntimeConfig(): TelegramRuntimeConfig {
+  const telegram = getTelegramConfig()
+  const botToken = telegram?.botToken?.trim()
+  const allowedUserIds = telegram?.allowedUserIds?.filter(Boolean) ?? []
+
+  if (!botToken) {
+    throw new Error('请先在 /telegram 中配置 Bot Token')
+  }
+
+  if (allowedUserIds.length === 0) {
+    throw new Error('请先在 /telegram 中配置允许访问的 Telegram user id')
+  }
+
+  return {
+    botToken,
+    allowedUserIds,
+  }
+}

src/services/telegram/telegramTypes.ts

@@ -0,0 +1,69 @@
+import type { TelegramConfig } from '../../utils/config.js'
+
+export const TELEGRAM_CHANNEL_SERVER = 'telegram'
+
+export type TelegramRuntimeConfig = {
+  botToken: string
+  allowedUserIds: string[]
+}
+
+export type TelegramServiceStatus = 'stopped' | 'starting' | 'running'
+
+export type TelegramServiceState = {
+  status: TelegramServiceStatus
+  botUsername?: string
+  botDisplayName?: string
+  lastError?: string
+  startedAt?: string
+  activeChatId?: string
+  activeUserId?: string
+}
+
+export type TelegramInboundEvent = {
+  kind: 'inbound-message'
+  chatId: string
+  userId: string
+  text: string
+  messageId: number
+  updateId: number
+}
+
+export type TelegramUpdate = {
+  update_id: number
+  message?: {
+    message_id: number
+    text?: string
+    chat?: {
+      id?: number
+      type?: string
+    }
+    from?: {
+      id?: number
+      is_bot?: boolean
+    }
+  }
+}
+
+export type TelegramGetMeResponse = {
+  ok: boolean
+  description?: string
+  result?: {
+    id: number
+    is_bot: boolean
+    first_name?: string
+    username?: string
+  }
+}
+
+export type TelegramGetUpdatesResponse = {
+  ok: boolean
+  description?: string
+  result?: TelegramUpdate[]
+}
+
+export type TelegramSendMessageResponse = {
+  ok: boolean
+  description?: string
+}
+
+export type TelegramConfigDraft = Partial<TelegramConfig>

src/utils/config.ts

@@ -590,6 +590,18 @@ export type GlobalConfig = {
   // CURRENT_MIGRATION_VERSION, runMigrations() skips all sync migrations
   // (avoiding 11× saveGlobalConfig lock+re-read on every startup).
   migrationVersion?: number
+
+  // Telegram bot bridge configuration (/telegram)
+  telegram?: TelegramConfig
+}
+
+export type TelegramConfig = {
+  botToken?: string
+  allowedUserIds?: string[]
+  autoStart?: boolean
+  lastAuthorizedUserId?: string
+  lastChatId?: string
+  updatedAt?: string
 }
 
 /**