Telegram 通道

网关控制台 — 即时通讯

网关运行时可使用 React 控制台中的 即时通讯 专页：

路由： #/channels（侧栏 即时通讯）。
前提： 已在设置中保存 网关访问令牌，以便调用需鉴权的 API。
当前产品界面： 仅配置微信与 Telegram。

多账户配置

json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "personal": {
          "name": "Personal Bot",
          "botToken": "BOT_TOKEN_1",
          "dmPolicy": "allowlist",
          "groupPolicy": "open",
          "allowFrom": [123456789],
          "streamMode": "partial"
        },
        "work": {
          "name": "Work Bot",
          "botToken": "BOT_TOKEN_2",
          "dmPolicy": "disabled",
          "groupPolicy": "allowlist",
          "groups": {
            "-1001234567890": {
              "requireMention": true,
              "systemPrompt": "You are a work assistant"
            }
          }
        }
      }
    }
  }
}

访问控制策略

DM 策略（dmPolicy）：

pairing — 未在允许列表中的用户不会进入智能体。允许来源：xopc.json 中的 allowFrom，以及 ~/.xopc/credentials/xopc-telegram-<账号>-allowFrom.json 里已批准的 id（可用 XOPC_CREDENTIALS_DIR 覆盖目录）。首次私聊会收到 配对码；管理员在网关所在机执行 xopc channels pairing approve --channel telegram --account <账号> <配对码>。详见 DM 私聊配对与 CLI — channels。
allowlist — 同样合并配置与凭证文件中的 id，但不发配对码；未命中则丢弃。
open — 任意用户可私聊。
disabled — 关闭私聊。

群组策略 (groupPolicy)：

open - 允许所有群
allowlist - 仅允许指定群
disabled - 禁用群

流式输出

Stream 模式 (streamMode)：

模式	说明
`off`	一次性发送完整消息
`partial`	流式发送 AI 回复，并展示工具进度
`block`	更完整的流式（含更多更新）

获取 Bot Token

打开 Telegram，搜索 @BotFather
发送 /newbot 创建机器人
按提示设置名称与用户名
复制生成的 Token

语音消息（STT/TTS）

详情见语音（STT/TTS）。

在需要 @mention 的 Telegram 群/超级群中，纯语音消息会在 mention 过滤前先做转写，这样“口播 bot 名称”（以及更适合 STT 的别名）也能触发。

反向代理配置

在受限网络环境下可设置自定义 API 根地址：

json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": {
          "botToken": "YOUR_BOT_TOKEN",
          "apiRoot": "https://your-proxy-domain.com"
        }
      }
    }
  }
}

启动时会自动验证连接。

使用限制

仅群/私聊：不支持广播频道（Channel）
轮询模式：使用 long polling，约 1-2 秒延迟
语音消息：STT 60 秒限制（Telegram）
TTS 文本：受 tts.maxTextLength 限制（schema 默认 512；可配置）

Telegram 通道 ​

网关控制台 — 即时通讯 ​

多账户配置 ​

访问控制策略 ​

流式输出 ​

获取 Bot Token ​

语音消息（STT/TTS） ​

反向代理配置 ​

使用限制 ​