跳到主要内容

Telegram 设置

KOPI AI AGENT 与 Telegram 集成为一个功能齐全的对话机器人。连接完成后,你可以在任意设备上与 agent 对话、发送会自动转录的语音备忘、接收定时任务结果,并在群聊中使用该 agent。此集成基于 python-telegram-bot 构建,支持文本、语音、图片和文件附件。

步骤 1:通过 BotFather 创建机器人​

每个 Telegram 机器人都需要由 @BotFather(Telegram 的官方机器人管理工具)签发的 API token。

  1. 打开 Telegram 并搜索 @BotFather,或访问 t.me/BotFather
  2. 发送 /newbot
  3. 选择一个显示名称(例如 "KOPI AI AGENT")——可以是任意名称
  4. 选择一个用户名——它必须唯一且以 bot 结尾(例如 my_kopi_bot)
  5. BotFather 会回复你的 API token,它看起来像这样:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
注意

请妥善保管你的机器人 token。任何拿到该 token 的人都能控制你的机器人。如果泄露,请立即通过 BotFather 中的 /revoke 吊销它。

步骤 2:自定义你的机器人(可选)​

以下 BotFather 命令可以改善用户体验。向 @BotFather 发消息并使用:

命令用途
/setdescription用户开始聊天前显示的"这个机器人能做什么?"文本
/setabouttext机器人资料页上的简短文本
/setuserpic为你的机器人上传头像
/setcommands定义命令菜单(聊天中的 / 按钮)
/setprivacy控制机器人是否接收所有群消息(参见步骤 3)
提示

对于 /setcommands,以下是一套实用的起始配置:

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

在线/离线状态指示器(可选)​

Telegram 机器人没有真正的在线/离线状态圆点——那个绿点是用户账号的功能,并非 Bot API 为机器人暴露的能力。最接近的展示位置是机器人的简短描述(即机器人资料页中名称下方的那一行)。

启用 status_indicator 后,Kopi Agent 会在网关连接时将该简短描述设置为 Online,在正常关闭时设置为 Offline:

gateway:
platforms:
telegram:
extra:
status_indicator: true
# Optional custom strings (defaults: "Online" / "Offline"):
status_online: "🟢 Online"
status_offline: "🔴 Offline"

注意事项:

  • 该简短描述对机器人是全局的(对所有用户可见),而不是按聊天区分的。用户在机器人资料页上看到它,而不是在打开的聊天中作为实时徽标显示。
  • 只有正常关闭网关(/stop、disconnect)才会写入 "Offline"。硬崩溃会保留最后已知状态——这是基于资料文本的指示器的固有局限。
  • 默认关闭,因为它会修改机器人的全局资料。

命令菜单优先级与上限(可选)​

Kopi Agent 会在 Telegram 网关启动时自动注册命令菜单。菜单由中心化的 slash 命令注册表加上符合条件的 plugin/skill 命令构建而成,然后会进行截断,以确保 Telegram 能可靠地接收该负载。默认上限为 60 条命令——足以保留所有内置命令以及常见的 skill 命令。

如果你有希望在 Telegram 的 / 选择器中保持可见的本地或 plugin 命令,请在 ~/.kopi/config.yaml 中为其设置优先级:

platforms:
telegram:
extra:
command_menu:
max_commands: 60
priority_mode: prepend # prepend | append | replace
priority:
- my_plugin_command

priority_mode 控制你的列表如何与 Kopi Agent 的内置优先级列表合并:

  • prepend:将你的命令放在最前面,然后是 Kopi Agent 的默认命令
  • append:保持 Kopi Agent 的默认命令在前,然后是你的命令
  • replace:仅使用你的列表进行优先级排序

Telegram 最多允许 100 条 BotCommands,但过大的命令负载可能会失败。为保证可靠性,Kopi Agent 默认使用 60,并将配置的值限制在 1..100;如需查看完整命令列表,请使用 /commands。

步骤 3:隐私模式(群聊中至关重要)​

Telegram 机器人有一个默认启用的隐私模式。这是在群聊中使用机器人时最常见的困惑来源。

隐私模式开启时,你的机器人只能看到:

  • 以 / 命令开头的消息
  • 直接回复机器人自身消息的回复
  • 服务消息(成员加入/退出、置顶消息等)
  • 机器人作为管理员的频道中的消息

隐私模式关闭时,机器人会接收群里的每一条消息。

如何禁用隐私模式​

  1. 给 @BotFather 发消息
  2. 发送 /mybots
  3. 选择你的机器人
  4. 进入 Bot Settings → Group Privacy → Turn off
注意

更改隐私设置后,你必须将机器人从所有群聊中移除并重新添加。Telegram 会在机器人加入群聊时缓存隐私状态,在移除并重新添加机器人之前不会更新。

提示

禁用隐私模式的替代方案:将机器人提升为群管理员。管理员机器人无论隐私设置如何都会接收所有消息,这样就无需切换全局隐私模式了。

观察群聊内容而不自动回复​

如需实现类似 OpenClaw/元宝 风格的群聊行为,可配置 Telegram,让机器人能够看到普通群消息,但只在被直接触发时才响应:

telegram:
allowed_chats:
- "-1001234567890"
group_allowed_chats:
- "-1001234567890"
require_mention: true
observe_unmentioned_group_messages: true

启用此模式后,来自明确列入白名单的聊天/话题的未提及群消息会被作为观察到的上下文追加到共享的聊天/话题会话记录中,但不会派发 agent。allowed_chats 决定机器人在哪些位置响应;group_allowed_chats 授权用于观察上下文的共享群会话,因此在此模式下请使用相同的 chat ID。之后在同一白名单聊天/话题中出现的 @botname 提及、对机器人的回复或配置的提及模式,都可以利用这些观察到的上下文。被触发的消息还会打上 [nickname|user_id] 标记,并附带逐轮安全提示,使模型将之前观察到的语句视为上下文,而非对机器人发出的指令。

等效的环境变量:

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

这需要 Telegram 将普通群消息传递给网关,因此请如上所述禁用 BotFather 的隐私模式或将机器人提升为群管理员。

步骤 4:查找你的 User ID​

KOPI AI AGENT 使用数字形式的 Telegram user ID 来控制访问权限。你的 user ID 不是你的用户名——它是一个类似 123456789 的数字。

方法 1(推荐): 给 @userinfobot 发消息——它会立即回复你的 user ID。

方法 2: 给 @get_id_bot 发消息——另一个可靠的选择。

请保存这个数字;下一步会用到它。

步骤 5:配置 Kopi Agent​

选项 A:交互式设置(推荐)​

kopi gateway setup

出现提示时选择 Telegram。配置向导会询问你的 bot token 和允许访问的 user ID,然后为你写入配置。

选项 B:手动配置​

将以下内容添加到 ~/.kopi/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789 # Comma-separated for multiple users

启动 Gateway​

kopi gateway

bot 应该会在几秒内上线。在 Telegram 上给它发一条消息以验证。

从 Docker 后端终端发送生成的文件​

如果你的终端后端是 docker,请记住 Telegram 附件是由 gateway 进程发送的,而不是从容器内部发送。这意味着最终的 MEDIA:/... 路径必须在运行 gateway 的主机上可读。

常见陷阱:

  • agent 在 Docker 内部将文件写入 /workspace/report.txt
  • 模型发出 MEDIA:/workspace/report.txt
  • Telegram 投递失败,因为 /workspace/report.txt 只存在于容器内部,而不在主机上

推荐的模式:

terminal:
backend: docker
docker_volumes:
- "/home/user/.kopi/cache/documents:/output"

然后:

  • 在 Docker 内部将文件写入 /output/...
  • 在 MEDIA: 中发出主机可见的路径,例如: MEDIA:/home/user/.kopi/cache/documents/report.txt

如果你已经有了 docker_volumes: 部分,请将新的挂载添加到同一个列表中。YAML 中的重复键会静默覆盖前面的键。

支持的 MEDIA: 文件扩展名​

gateway 会从 agent 的回复中提取 MEDIA:/path/to/file 标签,并将被引用的文件作为平台原生附件发送。所有 gateway 平台支持的扩展名:

类别扩展名
图片png, jpg, jpeg, gif, webp, bmp, tiff, svg
音频mp3, wav, ogg, m4a, opus, flac, aac
视频mp4, mov, webm, mkv, avi
文档pdf, txt, md, csv, json, xml, html, yaml, yml, log
Officedocx, xlsx, pptx, odt, ods, odp
压缩包zip, rar, 7z, tar, gz, bz2
电子书 / 软件包epub, apk, ipa

此列表中的任何文件类型,在支持的平台(Telegram、Discord、Signal、Slack、WhatsApp、Feishu、Matrix 等)上都会以原生附件形式投递;在不支持原生附件的平台上,则会回退为链接或纯文本指示符。加粗的类别是在最近几个版本中新增的——如果你之前依赖模型输出 here is the file: /path/to/report.docx,请改为使用 MEDIA:/path/to/report.docx 以获得原生投递。

Webhook 模式​

默认情况下,Kopi Agent 使用**长轮询(long polling)**连接 Telegram——gateway 主动向 Telegram 的服务器发起出站请求以获取新的更新。这种方式适用于本地部署和常开运行的部署。

对于云端部署(Fly.io、Railway、Render 等),webhook 模式更节省成本。这些平台可以在收到入站 HTTP 流量时自动唤醒挂起的机器,但出站连接不行。由于轮询是出站的,轮询 bot 永远无法休眠。Webhook 模式反转了方向——Telegram 将更新推送到你的 bot 的 HTTPS URL,从而实现空闲时休眠的部署。

轮询(默认)Webhook
方向Gateway → Telegram(出站)Telegram → Gateway(入站)
最适合本地、常开运行的服务器支持自动唤醒的云平台
设置无需额外配置设置 TELEGRAM_WEBHOOK_URL
空闲成本机器必须保持运行机器可在消息之间休眠

配置​

将以下内容添加到 ~/.kopi/.env:

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)" # required
# TELEGRAM_WEBHOOK_PORT=8443 # optional, default 8443
变量是否必需描述
TELEGRAM_WEBHOOK_URL是Telegram 发送更新所用的公开 HTTPS URL。URL 路径会被自动提取(例如,从上面的示例中提取 /telegram)。
TELEGRAM_WEBHOOK_SECRET是(当设置了 TELEGRAM_WEBHOOK_URL 时)Telegram 在每个 webhook 请求中回传的 secret token,用于验证。缺少它时 gateway 将拒绝启动——参见 GHSA-3vpc-7q5r-276h。使用 openssl rand -hex 32 生成。
TELEGRAM_WEBHOOK_PORT否webhook 服务器监听的本地端口(默认:8443)。

当设置了 TELEGRAM_WEBHOOK_URL 时,gateway 会启动一个 HTTP webhook 服务器而不是进行轮询。未设置时则使用轮询模式——与之前版本的行为一致。

云端部署示例(Fly.io)​

  1. 将环境变量添加到你的 Fly.io 应用 secrets 中:
fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)
  1. 在你的 fly.toml 中暴露 webhook 端口:
[[services]]
internal_port = 8443
protocol = "tcp"

[[services.ports]]
handlers = ["tls", "http"]
port = 443
  1. 部署:
fly deploy

gateway 日志应显示:[telegram] Connected to Telegram (webhook mode)。

代理支持​

如果 Telegram 的 API 被屏蔽,或者你需要通过代理路由流量,可以设置 Telegram 专用的代理 URL。它的优先级高于通用的 HTTPS_PROXY / HTTP_PROXY 环境变量。

选项 1:config.yaml(推荐)

telegram:
proxy_url: "socks5://127.0.0.1:1080"

选项 2:环境变量

TELEGRAM_PROXY=socks5://127.0.0.1:1080

支持的协议:http://、https://、socks5://。

该代理同时作用于 Telegram 主连接和回退的 IP 传输通道。如果没有设置 Telegram 专用代理,gateway 会回退到 HTTPS_PROXY / HTTP_PROXY / ALL_PROXY(或 macOS 系统代理自动检测)。

主频道​

在任意 Telegram 聊天(私聊或群组)中使用 /sethome 命令,即可将其指定为主频道。定时任务(cron job)会将结果发送到该频道。

你也可以在 ~/.kopi/.env 中手动设置:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"
提示

群聊 ID 是负数(例如 -1001234567890)。你的个人私聊 ID 与你的用户 ID 相同。

话题模式下的 cron 投递​

如果你在机器人私聊中启用了话题模式,投递到根聊天的 cron 消息会进入仅系统使用的 lobby —— 在那里回复不会开启任何会话,并且你会看到"主聊天保留给系统命令"的提示。请创建一个专用的论坛话题(例如 Cron),并设置:

TELEGRAM_CRON_THREAD_ID=<topic_thread_id>

TELEGRAM_CRON_THREAD_ID 仅在 cron 投递时覆盖 TELEGRAM_HOME_CHANNEL_THREAD_ID。该话题中的回复会继续使用该话题现有的会话。

语音消息​

接收语音(语音转文字)​

你在 Telegram 上发送的语音消息会被 Kopi Agent 配置的 STT provider(语音转文字服务提供商)自动转写,并以文本形式注入对话。

  • local 在运行 Kopi Agent 的机器上使用 faster-whisper —— 无需 API key
  • groq 使用 Groq Whisper,需要 GROQ_API_KEY
  • openai 使用 OpenAI Whisper,需要 VOICE_TOOLS_OPENAI_KEY

跳过 STT:将原始音频文件传给 agent​

如果你希望由 agent 本身处理音频 —— 例如说话人分离、自定义转写工具,或仅仅是归档录音 —— 请在 ~/.kopi/config.yaml 中设置 stt.enabled: false:

stt:
enabled: false

禁用 STT 后,网关仍会将语音/音频附件下载到 Kopi Agent 的音频缓存中,但不会进行转写。agent 会收到带有一个类似如下标记的消息:

[The user sent a voice message: /home/<user>/.kopi/cache/audio/<hash>.ogg]

随后你的工具或 skill 可以直接读取该路径(例如交给本地说话人分离流水线、更强的转写模型,或上传到长期存储)。文件扩展名反映了 Telegram 交付的原始格式(语音消息为 .ogg,音频附件为 .mp3/.m4a 等)。

这与下文的本地 Bot API server 一节天然契合,后者可将 Telegram 的 20MB getFile 上限提升到 2GB —— 当你要处理的录音超过几分钟时非常有用。

发送语音(文字转语音)​

当 agent 通过 TTS 生成音频时,会以原生 Telegram 语音气泡的形式发送 —— 即那种圆形的、可内联播放的形式。

  • OpenAI 和 ElevenLabs 原生生成 Opus —— 无需额外设置
  • Edge TTS(默认的免费 provider)输出 MP3,需要 ffmpeg 将其转换为 Opus:
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

没有 ffmpeg 时,Edge TTS 的音频会以普通音频文件形式发送(仍然可播放,但使用矩形播放器而非语音气泡)。

在你的 config.yaml 中的 tts.provider 键下配置 TTS provider。

通过本地 Bot API Server 传输大文件(>20MB)​

Telegram 的公共 Bot API 将 getFile 下载限制在 20 MB,因此任何超过该大小的语音消息、音频文件、视频或文档都会被 Kopi Agent 静默拒绝,并回复"too large"。官方文档中给出的解决方法是运行一个本地 telegram-bot-api daemon —— 与 Telegram 使用的服务器软件相同,但运行在你自己的网络中。本地服务器将文件上限提升至 2 GB,当检测到配置了自定义 base_url 时,Kopi Agent 会自动解除自身的内部上限。

这解锁了如下工作流:

  • 向 bot 发送长语音备忘录(45 分钟的会议、播客)
  • 上传大型视频供 vision 工具处理
  • 归档原始音频,用于说话人分离(diarization)、对齐或训练数据等离线流水线

第 1 步:获取 Telegram API 凭据​

本地服务器直接与 Telegram 的 MTProto 层通信(而非公共 Bot API),因此需要 MTProto 凭据:

  1. 访问 my.telegram.org/apps 并用你的 Telegram 账号登录。
  2. 创建一个新应用(任意名称和简短描述都可以)。
  3. 复制 api_id 和 api_hash —— 两者都是必需的。

第 2 步:运行 telegram-bot-api 服务器​

社区维护的 aiogram/telegram-bot-api Docker 镜像是最简单的途径。一个最小化的 docker-compose.yaml(使用 --local 模式以启用更高的限制):

services:
tg-bot-api:
image: aiogram/telegram-bot-api:latest
container_name: tg-bot-api
restart: unless-stopped
ports:
- "127.0.0.1:8081:8081" # bind to loopback only; see security note
environment:
TELEGRAM_API_ID: "12345" # your api_id from Step 1
TELEGRAM_API_HASH: "abcdef..." # your api_hash from Step 1
TELEGRAM_LOCAL: "1" # enable --local mode (raises 20MB → 2GB)
volumes:
- ./tg-bot-api-data:/var/lib/telegram-bot-api

启动它:

docker compose up -d tg-bot-api
docker logs --tail 20 tg-bot-api
安全性

本地 Bot API 服务器会将你的 bot token 放在 URL 路径中(例如 /bot<TOKEN>/getMe),且没有额外的身份验证。任何能访问该端口的人都可以完全控制你的 bot —— 读取它能看到的每条消息、以它的身份发送消息等。请将容器绑定到 127.0.0.1,并/或在私有网络上为其加一层反向代理。切勿将 8081 端口暴露到公共互联网。

第 3 步:将 bot 从公共 API 登出(仅需一次)​

一个 bot 同一时间只能在一个 Bot API 服务器上处于活跃状态。如果你的 bot 之前已经连接 api.telegram.org 运行(几乎可以肯定如此),你必须先在那里显式将其登出,本地服务器才会接受它:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/logOut"
# expected response: {"ok":true,"result":true}

这是一次性的迁移步骤 —— 无需在每次重启时重复执行。Telegram 会改为通过新服务器投递 logOut 之后收到的所有消息。

验证本地服务器能够代表该 bot 与 Telegram 通信:

curl "http://127.0.0.1:8081/bot<YOUR_BOT_TOKEN>/getMe"
# expected response: {"ok":true,"result":{"id":...,"is_bot":true,...}}

第 4 步:让 Kopi Agent 指向本地服务器​

在 ~/.kopi/config.yaml 的 platforms.telegram.extra 下添加 URL:

platforms:
telegram:
extra:
base_url: "http://127.0.0.1:8081/bot"
base_file_url: "http://127.0.0.1:8081/file/bot"
local_mode: true # see Step 5 below — only set this if the bot's data
# directory is readable by the Kopi Agent process
使用 platforms.telegram.extra,而不是 telegram.extra

目前只有 platforms.<name>.extra 形式的配置会被深度合并(deep-merge)到平台 config 中。直接放在顶层 telegram.extra 块下的键会被静默丢弃。

设置 base_url 后,Kopi Agent 会:

  • 基于本地服务器构建 python-telegram-bot 客户端
  • 将内部的文档/音频大小上限从 20 MB 自动提升至 2 GB
  • 在"too large"错误消息中报告当前生效的限制(Maximum: 2048 MB.),以便清楚地知道你处于哪种模式

重启 gateway 并查找确认日志行:

kopi gateway restart
grep -E "Using custom Telegram base_url|Using Telegram local_mode" ~/.kopi/logs/gateway.log | tail

第 5 步:local_mode —— 磁盘上的文件访问​

本地服务器有两种方式来传输文件:

  1. 不使用 --local(默认):文件通过 /file/bot<TOKEN>/<path> 上的 HTTP 提供,与公共 Bot API 相同。20MB 的上限仍然有效。仅适合作为网络问题的修复手段(例如 api.telegram.org 不可达但你可以自建托管);不适合用于提升大小限制。
  2. 使用 --local(通过上文的 TELEGRAM_LOCAL=1 设置):文件会被写入服务器的文件系统,getFile 响应返回一个绝对路径而非 HTTP URL。20MB 的上限被解除。此时 Kopi Agent 必须从磁盘读取字节,而不是通过 HTTP。

要让磁盘读取路径正常工作,需要在上文的配置中设置 local_mode: true,并确保 Kopi Agent 进程能够读取服务器返回的路径。有两种场景:

  • 同一台机器 —— telegram-bot-api 与 Kopi Agent 运行在同一主机上。将数据卷绑定挂载到 Kopi Agent 可读取的目录(例如 /var/lib/telegram-bot-api),并确保文件属主匹配。容器会降权到其内部的 telegram-bot-api 用户(uid 因镜像而异);最简单的修复方法是向 compose 服务添加 user: "<UID>:<GID>",使文件归属于 Kopi Agent 已经以该 uid 运行的所有者。
  • 不同的机器 —— bot 服务器运行在一台主机上(例如 NAS、独立的虚拟机),而 Kopi Agent 运行在另一台上。服务器的数据目录必须以服务器报告的相同绝对路径(通常是 /var/lib/telegram-bot-api)共享给 Kopi Agent 所在的机器。NFS 在这种场景下表现良好;如果你不想在文件系统层面处理 uid 不匹配问题,带 uid= 挂载重映射的 CIFS/SMB 会更友好。

如果设置了 local_mode: true,但 Kopi Agent 无法 stat 返回的文件路径(权限问题或挂载点错误),python-telegram-bot 会静默回退为向本地服务器发起 HTTP getFile —— 而在 --local 模式下,服务器会返回 404 Not Found。该症状会在 gateway.log 中表现为:

[Telegram] Failed to cache voice: Not Found
telegram.error.InvalidToken: Not Found

如果你看到这个,说明上限提升已生效,但文件共享没有生效。请以 gateway 运行所用的用户从 Kopi Agent 主机验证 ls -la /var/lib/telegram-bot-api/<TOKEN>/voice/,并确认单个文件可以被 cat 且不会出现权限错误。

第 6 步:测试​

向 bot 发送一条超过 20 MB 的语音消息或音频文件。跟踪 gateway 日志:

tail -f ~/.kopi/logs/gateway.log | grep -iE "telegram|cache"

你应该会看到一行 [Telegram] Cached user voice at /home/<user>/.kopi/cache/audio/...,而不会看到"too large"拒绝。结合上文的 stt.enabled: false,原始音频文件的路径随后会进入 agent 的入站消息中,供后续处理使用。

群聊使用​

KOPI AI AGENT 可在 Telegram 群聊中使用,但有几点需要注意:

  • **Privacy mode(隐私模式)**决定了机器人能看到哪些消息(参见第 3 步)
  • TELEGRAM_ALLOWED_USERS 同样适用——即便在群聊中,也只有获授权的用户才能触发机器人
  • 你可以通过 telegram.require_mention: true 阻止机器人响应群内的普通聊天
  • 使用 telegram.require_mention: true 时,符合以下条件的群消息会被接受:
    • 对机器人某条消息的回复
    • @botusername 提及(mention)
    • /command@botusername(Telegram 中包含机器人名称的机器人菜单命令形式)
    • 与 telegram.mention_patterns 中配置的某个 regex 唤醒词匹配
  • 当一个群中存在多个 Kopi Agent 机器人时,telegram.exclusive_bot_mentions 可确保路由确定性。当某条消息明确提及了一个或多个 Telegram 机器人用户名时,只有被提及的 bot profile 会处理该消息;其他 Kopi Agent 机器人会在运行回复和唤醒词回退之前忽略该消息。此功能默认启用。
  • 使用 telegram.ignored_threads 可让 Kopi Agent 在指定的 Telegram forum topic 中保持静默,即使该群本允许自由回复或由提及触发回复
  • 如果 telegram.require_mention 未设置或为 false,Kopi Agent 将保持此前的开放群行为,对其能看到的普通群消息进行回复

在一个群中使用多个 Kopi Agent 机器人​

如果你在同一 Telegram 群中运行多个 Kopi Agent profile,请为每个 profile 创建一个 Telegram bot token,并为每个 profile 启动一个 gateway。不要在多个运行中的 gateway 间复用同一个 bot token;Telegram 会拒绝针对同一 token 的并发轮询。

推荐的群配置:

telegram:
require_mention: true
exclusive_bot_mentions: true
mention_patterns: []

在此配置下,类似 @research_bot @ops_bot summarize this 的群消息只会由 research_bot 和 ops_bot 处理。群中其他 Kopi Agent 机器人将保持静默,即使该消息是对它们此前某条消息的回复,或原本会匹配到共享的唤醒词。

仅对于希望明确提及不应覆盖回复和唤醒词触发的旧版群组,才设置 exclusive_bot_mentions: false。

要运行多个 profile,请为每个 profile 执行一次 gateway 命令。例如:

# default profile
kopi gateway start
kopi gateway status
kopi gateway stop

# named profiles
kopi -p research gateway start
kopi -p research gateway status
kopi -p research gateway stop

对于小规模固定部署,可使用 shell 循环或脚本,为默认 profile 调用 kopi gateway <action>,为每个具名 profile 调用 kopi -p <profile> gateway <action>。这比假设单个进程级命令能在每种服务管理器上控制所有具名 profile 更为可靠。

故障排查:私聊正常但群聊无响应​

如果机器人在私聊中有响应,但在群聊中保持静默,请按顺序检查以下 环节:

  1. **Telegram 投递:**关闭 BotFather 的 privacy mode,将机器人提升为 admin,或直接提及该机器人。对于 Telegram 从未投递给机器人的群消息, Kopi Agent 无法做出响应。
  2. **修改隐私设置后重新加入群:**将机器人移出群聊,并在更改 BotFather 隐私 设置后重新添加。Telegram 可能对现有成员关系保留旧的 投递行为。
  3. **Kopi Agent 授权:**确认发送者已列入 TELEGRAM_ALLOWED_USERS 或 TELEGRAM_GROUP_ALLOWED_USERS,或通过 TELEGRAM_GROUP_ALLOWED_CHATS 允许该 群聊。
  4. **Mention 过滤器:**如果设置了 telegram.require_mention: true,普通 群聊内容将被忽略,除非消息是斜杠命令、对机器人的回复、 @botusername 提及,或匹配到配置的 mention_patterns。
  5. **多机器人路由:**如果一个群包含多个机器人,请确保每个 Kopi Agent profile 使用唯一的 bot token,并保持 exclusive_bot_mentions 处于启用状态,除非你有意采用旧的共享触发行为。

对于 Telegram 群组和超级群组,负数 chat ID 是正常的。如果你使用 按聊天范围的授权,请将这些 ID 放入 TELEGRAM_GROUP_ALLOWED_CHATS,而不是 发送者用户允许列表。

群触发配置示例​

将以下内容添加到 ~/.kopi/config.yaml:

telegram:
require_mention: true
exclusive_bot_mentions: true
mention_patterns:
- "^\\s*chompy\\b"
ignored_threads:
- 31
- "42"

此示例允许所有常见的直接触发方式,以及以 chompy 开头的消息,即使它们未使用 @mention。 在提及和自由回复检查运行之前,Telegram topic 31 和 42 中的消息始终会被忽略。

关于 mention_patterns 的说明​

  • 模式使用 Python 正则表达式
  • 匹配不区分大小写
  • 模式会同时针对文本消息和媒体说明文字进行检查
  • 无效的 regex 模式会在 gateway 日志中给出警告并被忽略,而不会导致机器人崩溃
  • 如果希望某个模式只匹配消息开头,请使用 ^ 将其锚定

私聊话题(Bot API 9.4)​

Telegram Bot API 9.4(2026 年 2 月)引入了私聊话题(Private Chat Topics)——bot 可以直接在一对一私聊中创建论坛式的话题线程,无需超级群组。这让你可以在与 Kopi Agent 的现有私聊中运行多个相互隔离的工作区。

用例​

如果你同时推进多个长期项目,话题可以让它们的上下文彼此隔离:

  • 话题 "Website" —— 用于生产环境 web 服务的开发
  • 话题 "Research" —— 文献综述与论文探索
  • 话题 "General" —— 杂项任务和快速提问

每个话题都有独立的会话、历史记录和上下文——与其他话题完全隔离。

配置​

前提条件

在将话题添加到配置之前,用户必须先在与 bot 的私聊中启用 Topics 模式:

  1. 在 Telegram 中打开与 Kopi Agent bot 的私聊
  2. 点击顶部的 bot 名称以打开聊天信息
  3. 启用 Topics(将聊天转为论坛的开关)

未启用时,Kopi Agent 会在启动时记录 The chat is not a forum 并跳过话题创建。这是 Telegram 的客户端设置——bot 无法通过编程方式启用它。

在 ~/.kopi/config.yaml 的 platforms.telegram.extra.dm_topics 下添加话题:

platforms:
telegram:
extra:
dm_topics:
- chat_id: 123456789 # Your Telegram user ID
topics:
- name: General
icon_color: 7322096
- name: Website
icon_color: 9367192
- name: Research
icon_color: 16766590
skill: arxiv # Auto-load a skill in this topic

字段:

字段必填说明
name是话题显示名称
icon_color否Telegram 图标颜色代码(整数)
icon_custom_emoji_id否话题图标的自定义 emoji ID
skill否在该话题中启动新会话时自动加载的 skill
thread_id否话题创建后自动填充——请勿手动设置

工作原理​

  1. 网关启动时,Kopi Agent 会为每个尚无 thread_id 的话题调用 createForumTopic
  2. thread_id 会自动保存回 config.yaml——后续重启将跳过该 API 调用
  3. 每个话题对应一个隔离的 session key:agent:main:telegram:dm:{chat_id}:{thread_id}
  4. 每个话题中的消息都有各自独立的对话历史、记忆刷新和上下文窗口

根私聊处理​

默认情况下,发送到根私聊(任何话题之外)的消息会正常处理。设置 ignore_root_dm: true 可将根私聊变成大厅——对于已配置 DM 话题的用户,普通消息会被静默忽略,而系统命令(/start、/help、/status 等)仍然可用。

platforms:
telegram:
extra:
ignore_root_dm: true
dm_topics:
- chat_id: 123456789
topics:
- name: General

该检查是按聊天进行的:只有在 dm_topics 中至少有一条记录的用户,其根私聊才会受影响。未配置话题的用户不受影响。

Skill 绑定​

带 skill 字段的话题会在该话题中新会话启动时自动加载对应的 skill。其效果与在对话开头输入 /skill-name 完全相同——skill 内容会被注入到第一条消息中,后续消息都能在对话历史中看到它。

例如,一个设置为 skill: arxiv 的话题会在其会话重置时(由于空闲超时、每日重置或手动 /reset)预加载 arxiv skill。

提示

在配置之外创建的话题(例如手动调用 Telegram API 创建)会在 forum_topic_created 服务消息到达时被自动发现。你也可以在网关运行期间向配置添加话题——它们会在下一次缓存未命中时被加载。

多会话 DM 模式(/topic)​

一种 ChatGPT 风格的多会话 DM —— 一个 bot,多个并行对话。与上面由运营者预先配置的 extra.dm_topics 不同,此模式是用户驱动的:无需配置,无需预先声明主题名称。终端用户通过 /topic 开启它,然后点击 Telegram 的 + 按钮即可创建任意多的主题,每个主题都是一个完全独立的 Kopi Agent 会话。

/topic 子命令​

形式上下文效果
/topic根 DM,尚未启用检查 BotFather 能力,启用多会话模式,创建置顶的 System 主题
/topic根 DM,已启用显示状态:可用于恢复的未关联会话
/topic主题内部显示当前主题的会话绑定
/topic help任意位置内联用法说明
/topic off根 DM禁用多会话模式并清除该聊天的所有主题绑定
/topic <session-id>主题内部将之前的 Telegram 会话恢复到当前主题

只有授权用户(通过 TELEGRAM_ALLOWED_USERS / 平台 auth config 设置的允许列表)才能运行 /topic。未授权的发送者会收到拒绝消息,而不是激活。

DM Topics 与多会话 DM 模式的对比​

extra.dm_topics(配置驱动)/topic(用户驱动)
谁来激活运营者,在 config.yaml 中终端用户,通过发送 /topic
主题列表配置中声明的固定集合用户自由创建/删除主题
主题名称由运营者选择由用户选择;自动重命名以匹配 Kopi Agent 会话标题
根 DM 行为普通聊天(若 ignore_root_dm: true 则为大厅)变为系统大厅(拒绝非命令消息)
主要使用场景带可选 skill 绑定的永久工作区临时的并行会话
持久化配置中的 extra.dm_topicstelegram_dm_topic_mode + telegram_dm_topic_bindings SQLite 表

这两个功能可以在同一个 bot 上共存 —— 你可以从用户的 DM 运行 /topic,而 extra.dm_topics 继续为其他聊天管理运营者声明的主题。

前提条件​

在 @BotFather 中,打开你的 bot → Bot Settings → Threads Settings:

  1. 打开 Threaded Mode(启用 has_topics_enabled)
  2. 不要禁用用户创建主题的功能(保持 allows_users_to_create_topics 开启)

当用户首次运行 /topic 时,Kopi Agent 会调用 getMe 来验证这两个标志。如果其中任一处于关闭状态,Kopi Agent 会发送一张 BotFather Threads Settings 页面的截图并解释需要切换哪些选项 —— 在前提条件满足之前不会进行激活。

激活流程​

从根 DM 发送:

/topic

Kopi Agent 将会:

  1. 检查 getMe().has_topics_enabled 和 allows_users_to_create_topics
  2. 如果两者都为 true,则为该 DM 启用多会话主题模式
  3. 创建并置顶一个 System 主题用于状态/命令(尽力而为)
  4. 回复一个用户可恢复的之前未关联 Telegram 会话的列表

激活后,根 DM 即为大厅:普通提示词会被拒绝,并附上指向 All Messages 的引导。系统命令(/status、/sessions、/usage、/help 等)在根中仍然有效。

创建新主题(终端用户流程)​

  1. 在 Telegram 中打开 bot DM
  2. 点击 bot 界面顶部的 All Messages,然后发送任意消息
  3. Telegram 会为该消息创建一个新主题
  4. Kopi Agent 在该主题内回复 —— 该主题现在就是一个独立的会话

每个主题都有自己的对话历史、模型状态、工具执行和会话 ID。隔离键是 agent:main:telegram:dm:{chat_id}:{thread_id} —— 与配置驱动的 DM 主题隔离完全一致。

自动重命名主题​

当 Kopi Agent 为主题生成会话标题时(通过自动标题流程,在首次对话之后),Telegram 主题本身也会被重命名以匹配 —— 例如 "New Topic" 会变成 "Database migration plan"。重命名是尽力而为的:失败会被记录,但不会中断会话。

要禁用此功能并保留你手动选择的主题名称,请设置:

gateway:
platforms:
telegram:
extra:
disable_topic_auto_rename: true

当此标志开启时,Kopi Agent 仍会生成内部会话标题(供 kopi sessions、TUI 等使用),但绝不会编辑 Telegram 主题名称。当你在 BotFather Threaded Mode 下手动整理主题、且不希望每次首次回复都覆盖标题时,这很有用。

主题内的 /new​

重置当前主题的会话(新的会话 ID,全新的历史),而不影响其他主题。Kopi Agent 会回复一条提醒:如果要进行并行工作,通常你需要的是创建另一个主题(通过 All Messages)。

恢复之前的会话​

在主题内发送:

/topic <session-id>

这会将当前主题绑定到一个现有的 Kopi Agent 会话,而不是重新开始。适用于继续在主题模式启用之前已经开始的对话。限制:

  • 目标会话必须属于同一个 Telegram 用户
  • 目标会话必须尚未绑定到其他主题

Kopi Agent 会通过会话标题进行确认,并重放最后一条助手消息以提供上下文。

要发现会话 ID,请在根 DM 中发送 /topic(不带参数)—— Kopi Agent 会列出该用户未关联的 Telegram 会话。

主题内的 /topic(不带参数)​

显示当前主题的绑定信息:会话标题、会话 ID,以及关于使用 /new 还是创建另一个主题的提示。

底层机制​

  • 激活状态持久化到 state.db 中的 telegram_dm_topic_mode(chat_id, user_id, enabled, ...)
  • 每个主题绑定持久化到 telegram_dm_topic_bindings(chat_id, thread_id, session_id, ...),并在 session_id 上设置 ON DELETE CASCADE —— 删除会话时会自动清除其主题绑定
  • 主题模式的 SQLite 迁移是可选加入的:它在首次 /topic 调用时运行,绝不会在 gateway 启动时运行。在用户于该 profile 中运行 /topic 之前,state.db 保持不变
  • 每条传入的 DM 消息都会查找其 (chat_id, thread_id) 绑定。如果存在,查找会通过 SessionStore.switch_session() 将消息路由到绑定的会话,从而保持 session-key 到 session-id 的映射在磁盘上的一致性
  • 主题内的 /new 会重写绑定行以指向新的会话 ID,因此下一条消息会继续停留在新会话中
  • 在 extra.dm_topics 中声明的主题永远不会被自动重命名 —— 即使启用了多会话模式,运营者选择的名称也会被保留
  • 设置 extra.disable_topic_auto_rename: true 可关闭该聊天中所有主题的自动重命名(包括通过 Threaded Mode 创建的临时主题)
  • 在启用 forum 的 DM 中,General(置顶于顶部)主题被视为根大厅,无论 Telegram 是通过 message_thread_id=1 还是不带 thread_id 来传递其消息
  • 根大厅的提醒有速率限制:每个聊天每 30 秒一条消息 —— 如果用户忘记了主题模式已开启,在根中输入十条提示词也不会收到十条回复
  • BotFather 设置截图有速率限制:每个聊天每 5 分钟发送一次 —— 在 Threads Settings 仍处于禁用状态时反复尝试 /topic 不会重新上传同一张图片
  • 在主题内启动的 /background <prompt> 会将其结果送回同一主题;后台会话不会触发所属主题的自动重命名
  • /topic 本身受 bot 的用户授权检查限制 —— 未授权的 DM 会收到拒绝消息,而不是激活

禁用多会话模式​

在根 DM 中发送 /topic off。Kopi Agent 会将该行关闭,清除该聊天的 (thread_id → session_id) 绑定,根 DM 将恢复为普通的 Kopi Agent 聊天。Telegram 中已存在的主题不会被删除 —— 它们只是不再作为独立会话进行管理。之后重新运行 /topic 即可重新开启。

如果你需要手动清理(例如对多个聊天进行批量重置),可以直接删除这些行:

sqlite3 ~/.kopi/state.db \
"UPDATE telegram_dm_topic_mode SET enabled = 0 WHERE chat_id = '<your_chat_id>'; \
DELETE FROM telegram_dm_topic_bindings WHERE chat_id = '<your_chat_id>';"

降级 Kopi Agent​

如果你降级到早于 /topic 的 Kopi Agent 版本,该功能将直接停止工作 —— telegram_dm_topic_mode 和 telegram_dm_topic_bindings 表会保留在 state.db 中,但会被旧代码忽略。DM 将恢复为原生的按线程隔离(每个 message_thread_id 仍会通过 build_session_key 获得自己的会话),因此你现有的 Telegram 主题仍可作为并行会话继续工作。根 DM 不再是大厅 —— 那里的消息会像以前一样进入 agent。重新升级后,多会话模式会在原来的位置精确恢复。

群组论坛话题 Skill 绑定​

启用了 Topics 模式(也称为"forum topics",即论坛话题)的超级群组已经具备按话题隔离的会话——每个 thread_id 映射到一个独立的对话。但你可能希望当消息出现在特定群组话题中时自动加载一个 skill,就像私聊话题 skill 绑定那样。

用例​

一个带有论坛话题、用于不同工作流的团队超级群组:

  • Engineering(工程)话题 → 自动加载 software-development skill
  • Research(研究)话题 → 自动加载 arxiv skill
  • General(通用)话题 → 不加载 skill,使用通用助手

配置​

在 ~/.kopi/config.yaml 的 platforms.telegram.extra.group_topics 下添加话题绑定:

platforms:
telegram:
extra:
group_topics:
- chat_id: -1001234567890 # Supergroup ID
topics:
- name: Engineering
thread_id: 5
skill: software-development
- name: Research
thread_id: 12
skill: arxiv
- name: General
thread_id: 1
# No skill — general purpose

字段说明:

字段是否必需描述
chat_id是超级群组的数字 ID(以 -100 开头的负数)
name否该话题的可读标签(仅作参考说明)
thread_id是Telegram 论坛话题 ID —— 可在 t.me/c/<group_id>/<thread_id> 链接中看到
skill否在该话题的新会话中自动加载的 skill

工作原理​

  1. 当消息到达已映射的群组话题时,Kopi Agent 会在 group_topics 配置中查找 chat_id 和 thread_id
  2. 如果匹配的条目包含 skill 字段,该 skill 就会为会话自动加载——与私聊话题 skill 绑定完全一致
  3. 没有 skill 键的话题只会获得会话隔离(即现有行为,保持不变)
  4. 未映射的 thread_id 值或 chat_id 值会被静默跳过——不报错,也不加载 skill

与私聊话题的差异​

私聊话题群组话题
配置键extra.dm_topicsextra.group_topics
话题创建如果缺少 thread_id,Kopi Agent 会通过 API 创建话题由管理员在 Telegram 界面中创建
thread_id创建后自动填充必须手动设置
icon_color / icon_custom_emoji_id支持不适用(外观由管理员控制)
Skill 绑定✓✓
会话隔离✓✓(论坛话题已内置)
提示

要查找话题的 thread_id,请在 Telegram Web 或桌面版中打开该话题并查看 URL:https://t.me/c/1234567890/5 —— 最后的数字(5)就是 thread_id。超级群组的 chat_id 是在群组 ID 前加上 -100 前缀(例如,群组 1234567890 变为 -1001234567890)。

近期 Bot API 功能​

  • Bot API 9.4(2026 年 2 月): 私聊话题——机器人可以通过 createForumTopic 在一对一直接消息(DM)聊天中创建论坛话题。Kopi Agent 将其用于两个不同的功能:由运营方策划的私聊话题(由 config 驱动、固定的话题列表)和由用户驱动的多会话私聊模式(通过 /topic 激活,用户可创建无限话题)。
  • 隐私政策: Telegram 现在要求机器人必须有隐私政策。请通过 BotFather 使用 /setprivacy_policy 设置,否则 Telegram 可能会自动生成一个占位内容。如果你的机器人面向公众,这一点尤其重要。
  • Bot API 9.5(2026 年 3 月):通过 sendMessageDraft 实现原生流式传输。 Kopi Agent 支持 Telegram 的原生流式草稿 API,作为私聊的可选传输方式。默认仍使用传统 editMessageText 路径,因为草稿预览在某些 Telegram 客户端上会明显地折叠并重新渲染。

流式传输方式(gateway.streaming.transport)​

启用流式传输后(gateway.streaming.enabled: true),Kopi Agent 会从以下四种传输方式中选择一种:

值行为
auto(默认)在支持的聊天(目前为 Telegram 私聊)上使用原生草稿流式传输;其他情况使用传统的基于编辑的路径。如果草稿帧失败,会优雅地回退。
draft强制使用原生草稿。如果聊天不支持草稿(例如群组/话题),会记录一次降级并回退到编辑方式。
edit对所有聊天类型使用传统的逐步 editMessageText 轮询。
off完全禁用流式传输(只发送最终回复,没有逐步更新)。

在 ~/.kopi/config.yaml 中:

gateway:
streaming:
enabled: true
transport: auto # auto | draft | edit | off

在私聊中使用 edit(默认)时你会看到什么 —— 网关发送一条正常的预览消息,并通过 editMessageText 逐步更新它,从而避免 Telegram 草稿预览的折叠/回滚效果。

在私聊中使用 auto 或 draft 时你会看到什么 —— Telegram 会显示一个逐 token 更新的动画草稿预览。回复完成后,会作为普通消息发送,草稿预览会在客户端自然清除。草稿没有 message id,因此最终答案会保留在你的聊天记录中。

群组、超级群组、论坛话题呢? Telegram 将 sendMessageDraft 限制为私聊(DM)。对于其他所有类型,网关会透明地回退到基于编辑的路径——用户体验与之前相同。

如果草稿帧失败会怎样? 任何失败(临时网络错误、服务端拒绝、较旧的 python-telegram-bot 安装)都会让该响应在本次流式传输的剩余部分切换回基于编辑的路径。下一次响应会重新尝试。

渲染:富文本消息、表格和链接预览​

富文本消息(Bot API 10.1)。 如果最终回复中包含旧版 MarkdownV2 路径无法良好呈现的结构——表格、任务列表、可折叠的 <details> 以及块级公式——将通过 Telegram 原生的 sendRichMessage 发送,使用 agent 的原始 markdown,从而实现原生渲染,无需在客户端进行扁平化处理。在流式传输过程中,最终回答通过 editMessageText 的 rich_message 参数就地编辑现有预览来送达——不发第二条消息,也不删除消息,因此在一轮对话结束时不会出现重复送达的闪烁。在私聊中,实时流式预览同样使用 sendRichMessageDraft,因此动态草稿与最终的富文本消息保持一致。普通回复(纯文本、粗体/斜体、简单列表)仍走 MarkdownV2 路径,以确保在各客户端上字体粗细和间距的一致性。

当内容超过 32,768 个字符的富文本上限时,富文本路径会被自动跳过;而 Telegram 的任何拒绝(旧版 python-telegram-bot 上不支持的 endpoint、解析错误、过大的块/列)都会透明地回退到 MarkdownV2 路径——你的消息绝不会丢失。瞬时/网络错误不会被静默重发(不会出现重复的最终消息)。

MarkdownV2 回退。 当某条消息无法使用富文本路径时,Kopi Agent 会将 markdown 转换为 MarkdownV2。由于 MarkdownV2 没有原生的表格语法,管道表格会被规范化处理:

  • 小表格会被扁平化为按行分组的项目符号列表——每一行在各列标题下变成一个可读的项目符号列表。适合 2–4 列且单元格较短的情况。
  • 更大或更宽的表格会回退为围栏代码块,并对齐各列,避免任何内容塌缩。

富文本消息需要主动启用。默认仍使用旧版 MarkdownV2 路径,因为当前的 Telegram 客户端可能让 Bot API 富文本消息难以复制为纯文本,这对命令片段和移动端交接尤其不便。要为表格/任务列表/details/公式启用原生渲染:

gateway:
platforms:
telegram:
extra:
rich_messages: true
rich_drafts: false

此设置用于客户端渲染/复制兼容性;当 Telegram 拒绝富文本 API 调用时,Kopi Agent 已经会自动回退。rich_drafts 控制 Telegram 私聊流式传输期间的实验性富文本草稿预览路径,默认关闭,因为在聊天重新绘制之前,Telegram Desktop/macOS 可能会在视觉上叠加富文本草稿帧。如果你只想保留旧版"始终使用代码块"的表格行为,同时保持富文本消息启用,可在 config.yaml 中设置 telegram.pretty_tables: false 来禁用表格规范化(默认:true)。

链接预览。 Telegram 会为 bot 消息中的 URL 自动生成链接预览。如果你更希望抑制这些预览(冗长的 /tools 输出、提到十个链接的 agent 回复等):

gateway:
platforms:
telegram:
extra:
disable_link_previews: true

启用后,Kopi Agent 会在每条发出的消息上附加 Telegram 的 LinkPreviewOptions(is_disabled=True),并在较旧的 python-telegram-bot 版本上回退到旧版 disable_web_page_preview 参数。

群组允许列表​

Telegram 群组和论坛聊天有两个相互独立的关卡,你可以分别配置:

  • 发送者 user ID(group_allow_from / TELEGRAM_GROUP_ALLOWED_USERS)——以发送者为范围的允许列表,仅适用于群组/论坛消息。当你希望特定用户能够在群组中调用 bot,而不把他们加入 TELEGRAM_ALLOWED_USERS(那也会赋予他们私聊权限)时,使用此项。
  • Chat ID(group_allowed_chats / TELEGRAM_GROUP_ALLOWED_CHATS)——以会话为范围的允许列表。这些群组/论坛的任何成员都可以与 bot 交互。适用于群组成员身份本身就是访问信号的团队/支持类 bot。
gateway:
platforms:
telegram:
extra:
# Global access (DMs + groups). Users here can always invoke the bot.
allow_from:
- "123456789"
# Sender IDs allowed in groups/forums only. Does NOT grant DM access.
group_allow_from:
- "987654321"
# Entire groups/forums — any member is authorized.
group_allowed_chats:
- "-1001234567890"

等效的环境变量:

TELEGRAM_ALLOWED_USERS="123456789"
TELEGRAM_GROUP_ALLOWED_USERS="987654321"
TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890"

行为:

  • TELEGRAM_ALLOWED_USERS 覆盖所有聊天类型(私聊、群组、论坛)。
  • TELEGRAM_GROUP_ALLOWED_USERS 仅授权群组/论坛中列出的发送者。除非他们也列在 TELEGRAM_ALLOWED_USERS 中,否则仍无法私聊 bot。
  • 列入 TELEGRAM_GROUP_ALLOWED_CHATS 的会话会授权该会话的每一位成员,无论发送者是谁。
  • 在其中任意一项中使用 * 即可允许任何发送者/会话。
  • 这是在现有 mention/pattern 触发器以及 group_topics + ignored_threads 之上叠加的。

从 PR #17686 之前迁移​

在此次拆分之前,TELEGRAM_GROUP_ALLOWED_USERS 是唯一的开关,用户在其中放入 chat ID。为了向后兼容,TELEGRAM_GROUP_ALLOWED_USERS 中形如 chat ID 的值(以 - 开头)仍会被当作 chat ID 处理,并记录一次弃用警告。迁移方式:

# Old (still works, but deprecated)
TELEGRAM_GROUP_ALLOWED_USERS="-1001234567890"

# New
TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890"

访客 @mention 绕过(guest_mode)​

在典型配置中,group_allowed_chats 是一道硬性关卡:来自列表之外群组的消息会被静默丢弃,即使某位成员显式 @mention 了 bot 也是如此。对于支持/团队类 bot,这是正确的默认行为。

对于更随性的场景——朋友群聊,你希望 bot 基本保持沉默,但偶尔可通过显式 ping 调用——请启用 guest_mode:

gateway:
platforms:
telegram:
extra:
group_allowed_chats:
- "-1001234567890" # your main allowlisted group
guest_mode: true # non-allowlisted groups: allow on @mention only

环境变量等效项:

TELEGRAM_GUEST_MODE=true

默认值:false。

启用 guest_mode: true 后,来自未列入允许列表群组的消息只有在显式 @mention bot 时才会被处理。每一回合都需要 mention——访客交互没有会话粘性,因此 bot 绝不会自动加入未被 ping 的朋友群聊线程。

私聊和已列入允许列表的群组的行为与之前完全一致。

斜杠命令访问控制​

默认情况下,允许列表中的每个用户都能运行所有斜杠命令。如果你想把允许列表区分为管理员(拥有完整斜杠命令访问权限)和普通用户(仅能使用你明确启用的命令),请在平台的 extra 块中添加 allow_admin_from 和 user_allowed_commands:

gateway:
platforms:
telegram:
extra:
# Existing allowlists (unchanged)
allow_from:
- "123456789" # admin
- "555555555" # regular user
- "777777777" # regular user

# NEW — admins get all slash commands (built-in + plugin)
allow_admin_from:
- "123456789"

# NEW — non-admin allowed users can only run these slash commands.
# /help and /whoami are always allowed so users can see their access.
user_allowed_commands:
- status
- model
- history

# Optional: separate admin/command lists for groups
group_allow_admin_from:
- "123456789"
group_user_allowed_commands:
- status

行为说明:

  • 在某个作用域(私聊或群组)的 allow_admin_from 中列出的用户,可以通过实时注册表运行每一个已注册的斜杠命令——包括内置命令和 plugin 注册的命令。
  • 在 allow_from 中但不在 allow_admin_from 中的用户,只能运行 user_allowed_commands 中列出的命令,以及始终允许的基础命令:/help 和 /whoami。
  • 普通聊天(非斜杠消息)不受影响。非管理员用户仍可正常与 agent 对话,只是无法触发任意命令。
  • 向后兼容: 如果某个作用域未设置 allow_admin_from,则该作用域的斜杠命令限制功能处于关闭状态。现有安装无需任何更改即可继续使用。
  • 私聊管理员身份并不意味着群组管理员身份。每个作用域都有各自的管理员列表。
  • 如果仅设置了 group_allow_admin_from,私聊作用域将保持不受限(向后兼容)模式。

使用 /whoami 可查看当前作用域、你的层级(admin / user / unrestricted),以及你可以运行哪些斜杠命令。

交互式模型选择器​

在 Telegram 聊天中发送不带参数的 /model 时,Kopi Agent 会显示一个交互式内联键盘,用于切换模型:

  1. 选择 provider(服务提供商) — 显示每个可用 provider 的按钮,并标注模型数量(例如 "OpenAI (15)"、当前 provider 显示为 "✓ Anthropic (12)")。
  2. 选择模型 — 分页显示模型列表,提供 Prev/Next 导航、返回 provider 的 Back 按钮以及 Cancel。

当前模型和 provider 显示在顶部。所有导航都通过就地编辑同一条消息完成(不会弄乱聊天记录)。

提示

如果你知道确切的模型名称,可直接输入 /model <name> 来跳过选择器。你也可以输入 /model <name> --global 来让更改跨会话持久保存。

DNS-over-HTTPS 回退 IP​

在某些受限网络中,api.telegram.org 可能会解析到无法访问的 IP。Telegram adapter 包含回退 IP 机制,会透明地重试连接到其他 IP,同时保留正确的 TLS 主机名和 SNI。

工作原理​

  1. 如果设置了 TELEGRAM_FALLBACK_IPS,则直接使用这些 IP。
  2. 否则,adapter 会通过 DNS-over-HTTPS(DoH)自动查询 Google DNS 和 Cloudflare DNS,以发现 api.telegram.org 的其他 IP。
  3. DoH 返回的、与系统 DNS 结果不同的 IP 将用作回退。
  4. 如果 DoH 也被封锁,则使用硬编码的种子 IP(149.154.167.220)作为最后手段。
  5. 一旦某个回退 IP 成功,它就会变为"粘性"——后续请求会直接使用它,而不会先重试主路径。

配置​

# Explicit fallback IPs (comma-separated)
TELEGRAM_FALLBACK_IPS=149.154.167.220,149.154.167.221

或者在 ~/.kopi/config.yaml 中:

platforms:
telegram:
extra:
fallback_ips:
- "149.154.167.220"
提示

通常无需手动配置此功能。通过 DoH 的自动发现机制可以应对大多数受限网络场景。只有当 DoH 在你的网络中也被封锁时,才需要设置 TELEGRAM_FALLBACK_IPS 环境变量。

代理支持​

如果你的网络需要通过 HTTP 代理访问互联网(在企业环境中很常见),Telegram adapter 会自动读取标准代理环境变量,并将所有连接通过代理路由。

支持的变量​

adapter 会按顺序检查以下环境变量,使用第一个已设置的变量:

  1. HTTPS_PROXY
  2. HTTP_PROXY
  3. ALL_PROXY
  4. https_proxy / http_proxy / all_proxy(小写变体)

配置​

在启动 gateway 之前,在环境中设置代理:

export HTTPS_PROXY=http://proxy.example.com:8080
kopi gateway

或者将其添加到 ~/.kopi/.env:

HTTPS_PROXY=http://proxy.example.com:8080

代理同时适用于主传输层和所有回退 IP 传输层。无需额外的 Kopi Agent 配置——只要设置了环境变量,就会自动使用。

备注

这涵盖 Kopi Agent 用于 Telegram 连接的自定义回退传输层。其他地方使用的标准 httpx 客户端本身已原生支持代理环境变量。

消息回应​

机器人可以为消息添加 emoji 回应,作为可视化的处理反馈:

  • 👀 表示机器人开始处理你的消息
  • ✅ 表示响应已成功送达
  • ❌ 表示处理过程中发生错误

回应默认处于关闭状态。可在 config.yaml 中启用:

telegram:
reactions: true

或通过环境变量启用:

TELEGRAM_REACTIONS=true
备注

与 Discord(回应是累加的)不同,Telegram 的 Bot API 会在单次调用中替换机器人的所有回应。从 👀 到 ✅/❌ 的转换是原子性的——你不会同时看到两者。

提示

如果机器人没有在群组中添加回应的权限,回应调用会静默失败,消息处理仍会正常继续。

按频道 Prompt​

为特定的 Telegram 群组或论坛话题分配临时 system prompt。该 prompt 会在每一轮对话时于运行时注入——永远不会持久化到对话历史中——因此更改会立即生效。

telegram:
channel_prompts:
"-1001234567890": |
You are a research assistant. Focus on academic sources,
citations, and concise synthesis.
"42": |
This topic is for creative writing feedback. Be warm and
constructive.

键是聊天 ID(群组/超级群组)或论坛话题 ID。对于论坛群组,话题级 prompt 会覆盖群组级 prompt:

  • 在群组 -1001234567890 中的话题 42 中发送消息 → 使用话题 42 的 prompt
  • 在话题 99 中发送消息(无显式条目)→ 回退到群组 -1001234567890 的 prompt
  • 在没有条目的群组中发送消息 → 不应用任何频道 prompt

YAML 中的数字键会自动规范化为字符串。

故障排查​

问题解决方案
Bot 完全没有响应验证 TELEGRAM_BOT_TOKEN 是否正确。检查 kopi gateway 日志中的错误。
Bot 响应"unauthorized"你的 user ID 不在 TELEGRAM_ALLOWED_USERS 中。用 @userinfobot 再次确认。
Bot 忽略群组消息很可能开启了 Privacy mode。关闭它(步骤 3),或将 bot 设为群组管理员。更改隐私设置后请务必移除并重新添加 bot。
语音消息未被转写验证 STT 是否可用:安装 faster-whisper 进行本地转写,或在 {(chat_id, status_key) → message_id} 中设置 GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY。
语音回复是文件而非气泡安装 ffmpeg(Edge TTS Opus 转换需要它)。
Bot token 已被吊销/无效通过 /revoke 生成新 token,然后在 BotFather 中 /newbot 或 /token。更新你的 .env 文件。
Webhook 未收到更新验证 TELEGRAM_WEBHOOK_URL 可公开访问(用 curl 测试)。确保你的平台/反向代理将来自该 URL 端口的入站 HTTPS 流量路由到 TELEGRAM_WEBHOOK_PORT 配置的本地监听端口(两者不必相同)。确保 SSL/TLS 已启用 —— Telegram 只向 HTTPS URL 发送。检查防火墙规则。

命令执行审批​

当 agent 尝试运行可能危险的命令时,会在聊天中请求你的批准:

⚠️ This command is potentially dangerous (recursive delete). Reply "yes" to approve.

回复 "yes"/"y" 表示批准,或 "no"/"n" 表示拒绝。

交互式提示(clarify)​

当 agent 调用 clarify 工具时 —— 用于询问你偏好的方案、获取任务后反馈,或在做出非简单决策前确认 —— Telegram 会使用内联键盘按钮渲染问题:

❓ Which framework should I use for the dashboard?

[1. Next.js] [2. Remix] [3. Astro] [✏️ Other (type answer)]

点击按钮即可回答,或点击 Other 输入自由格式的回复(你发送的下一条消息即成为答案)。开放式 clarify 调用(无预设选项)会跳过按钮,直接捕获你的下一条消息。

通过 ~/.kopi/config.yaml 中的 agent.clarify_timeout 配置响应超时(默认 600 秒)。如果在超时前未响应,agent 会用一条哨兵消息解除阻塞并进行适应,而不会一直挂起。

推送通知频率​

Telegram 会在 bot 发送的每条消息上触发推送通知。对于长时间的 agent 回合,如果产生工具进度气泡、流式更新和状态回调,通知很快就会变得很吵。Telegram adapter 提供两种通知模式:

模式行为
important(默认)仅最终响应、审批提示和斜杠命令确认会响铃。工具进度、流式分片和状态消息以 disable_notification=true 方式送达。
all每条发出的消息都会触发推送通知。这是旧行为;如果你确实想了解每次工具调用,可以主动开启。

在 ~/.kopi/config.yaml 中配置:

display:
platforms:
telegram:
notifications: important # or "all"

环境变量覆盖(适合快速 A/B 测试):

KOPI_TELEGRAM_NOTIFICATIONS=all

未知值会记录警告并回退到 important。

状态消息原地编辑​

Telegram adapter 通过 send_or_update_status() 路由重复出现的 agent 状态回调(例如 "Compressing context…"、"Calling tool…"),它维护一个 {(chat_id, status_key) → message_id} 缓存,并在后续发送时编辑现有气泡,而不是每次都追加新气泡。不同的 status_key 值各自拥有独立消息;不同聊天之间绝不会冲突。如果编辑失败(例如用户删除了该消息,或消息已超出 Telegram 允许编辑的时间),缓存条目会被丢弃,下一次发送会发布一条新消息并重新缓存其 ID。无需配置 —— 这是 Telegram 的默认行为。未实现 send_or_update_status 的其他 adapter 会照常退回到普通的 send()。

在 agent 回合期间置顶用户入站消息​

当用户发送触发 agent 回合的消息时,Telegram adapter 会在该回合期间置顶这条入站消息,并在响应完成后取消置顶 —— 作为轻量级的视觉指示,表明 bot 正在积极处理该消息而非忽略它。置顶使用 disable_notification=true 以避免额外的提示音。无需配置。

安全​

注意

务必设置 TELEGRAM_ALLOWED_USERS 来限制谁可以与你的 bot 交互。如果不设置,出于安全考虑,gateway 默认拒绝所有用户。

切勿公开分享你的 bot token。如果泄露,请立即通过 BotFather 的 /revoke 命令吊销它。

更多详情请参阅安全文档。你也可以使用 DM pairing 来实现更动态的用户授权方式。