Telegram 设置
KOPI AI AGENT 与 Telegram 集成为一个功能齐全的对话机器人。连接完成后,你可以在任意设备上与 agent 对话、发送会自动转录的语音备忘、接收定时任务结果,并在群聊中使用该 agent。此集成基于 python-telegram-bot 构建,支持文本、语音、图片和文件附件。
步骤 1:通过 BotFather 创建机器人
每个 Telegram 机器人都需要由 @BotFather(Telegram 的官方机器人管理工具)签发的 API token。
- 打开 Telegram 并搜索 @BotFather,或访问 t.me/BotFather
- 发送
/newbot - 选择一个显示名称(例如 "KOPI AI AGENT")——可以是任意名称
- 选择一个用户名——它必须唯一且以
bot结尾(例如my_kopi_bot) - 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 机器人有一个默认启用的隐私模式。这是在群聊中使用机器人时最常见的困惑来源。
隐私模式开启时,你的机器人只能看到:
- 以
/命令开头的消息 - 直接回复机器人自身消息的回复
- 服务消息(成员加入/退出、置顶消息等)
- 机器人作为管理员的频道中的消息
隐私模式关闭时,机器人会接收群里的每一条消息。
如何禁用隐私模式
- 给 @BotFather 发消息
- 发送
/mybots - 选择你的机器人
- 进入 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 |
| Office | docx, 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)
- 将环境变量添加到你的 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)
- 在你的
fly.toml中暴露 webhook 端口:
[[services]]
internal_port = 8443
protocol = "tcp"
[[services.ports]]
handlers = ["tls", "http"]
port = 443
- 部署:
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 keygroq使用 Groq Whisper,需要GROQ_API_KEYopenai使用 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 凭据:
- 访问 my.telegram.org/apps 并用你的 Telegram 账号登录。
- 创建一个新应用(任意名称和简短描述都可以)。
- 复制
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 —— 磁盘上的文件访问
本地服务器有两种方式来传输文件:
- 不使用
--local(默认):文件通过/file/bot<TOKEN>/<path>上的 HTTP 提供,与公共 Bot API 相同。20MB 的上限仍然有效。仅适合作为网络问题的修复手段(例如api.telegram.org不可达但你可以自建托管);不适合用于提升大小限制。 - 使用
--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 更为可靠。
故障排查:私聊正常但群聊无响应
如果机器人在私聊中有响应,但在群聊中保持静默,请按顺序检查以下 环节:
- **Telegram 投递:**关闭 BotFather 的 privacy mode,将机器人提升为 admin,或直接提及该机器人。对于 Telegram 从未投递给机器人的群消息, Kopi Agent 无法做出响应。
- **修改隐私设置后重新加入群:**将机器人移出群聊,并在更改 BotFather 隐私 设置后重新添加。Telegram 可能对现有成员关系保留旧的 投递行为。
- **Kopi Agent 授权:**确认发送者已列入
TELEGRAM_ALLOWED_USERS或TELEGRAM_GROUP_ALLOWED_USERS,或通过TELEGRAM_GROUP_ALLOWED_CHATS允许该 群聊。 - **Mention 过滤器:**如果设置了
telegram.require_mention: true,普通 群聊内容将被忽略,除非消息是斜杠命令、对机器人的回复、@botusername提及,或匹配到配置的mention_patterns。 - **多机器人路由:**如果一个群包含多个机器人,请确保每个
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 模式:
- 在 Telegram 中打开与 Kopi Agent bot 的私聊
- 点击顶部的 bot 名称以打开聊天信息
- 启用 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 | 否 | 话题创建后自动填充——请勿手动设置 |
工作原理
- 网关启动时,Kopi Agent 会为每个尚无
thread_id的话题调用createForumTopic thread_id会自动保存回config.yaml——后续重启将跳过该 API 调用- 每个话题对应一个隔离的 session key:
agent:main:telegram:dm:{chat_id}:{thread_id} - 每个话题中的消息都有各自独立的对话历史、记忆刷新和上下文窗口
根私聊处理
默认情况下,发送到根私聊(任何话题之外)的消息会正常处理。设置 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_topics | telegram_dm_topic_mode + telegram_dm_topic_bindings SQLite 表 |
这两个功能可以在同一个 bot 上共存 —— 你可以从用户的 DM 运行 /topic,而 extra.dm_topics 继续为其他聊天管理运营者声明的主题。
前提条件
在 @BotFather 中,打开你的 bot → Bot Settings → Threads Settings:
- 打开 Threaded Mode(启用
has_topics_enabled) - 不要禁用用户创建主题的功能(保持
allows_users_to_create_topics开启)
当用户首次运行 /topic 时,Kopi Agent 会调用 getMe 来验证这两个标志。如果其中任一处于关闭状态,Kopi Agent 会发送一张 BotFather Threads Settings 页面的截图并解释需要切换哪些选项 —— 在前提条件满足之前不会进行激活。
激活流程
从根 DM 发送:
/topic
Kopi Agent 将会:
- 检查
getMe().has_topics_enabled和allows_users_to_create_topics - 如果两者都为 true,则为该 DM 启用多会话主题模式
- 创建并置顶一个 System 主题用于状态/命令(尽力而为)
- 回复一个用户可恢复的之前未关联 Telegram 会话的列表
激活后,根 DM 即为大厅:普通提示词会被拒绝,并附上指向 All Messages 的引导。系统命令(/status、/sessions、/usage、/help 等)在根中仍然有效。
创建新主题(终端用户流程)
- 在 Telegram 中打开 bot DM
- 点击 bot 界面顶部的 All Messages,然后发送任意消息
- Telegram 会为该消息创建一个新主题
- 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-developmentskill - Research(研究)话题 → 自动加载
arxivskill - 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 |
工作原理
- 当消息到达已映射的群组话题时,Kopi Agent 会在
group_topics配置中查找chat_id和thread_id - 如果匹配的条目包含
skill字段,该 skill 就会为会话自动加载——与私聊话题 skill 绑定完全一致 - 没有
skill键的话题只会获得会话隔离(即现有行为,保持不变) - 未映射的
thread_id值或chat_id值会被静默跳过——不报错,也不加载 skill
与私聊话题的差异
| 私聊话题 | 群组话题 | |
|---|---|---|
| 配置键 | extra.dm_topics | extra.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 会显示一个交互式内联键盘,用于切换模型:
- 选择 provider(服务提供商) — 显示每个可用 provider 的按钮,并标注模型数量(例如 "OpenAI (15)"、当前 provider 显示为 "✓ Anthropic (12)")。
- 选择模型 — 分页显示模型列表,提供 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。
工作原理
- 如果设置了
TELEGRAM_FALLBACK_IPS,则直接使用这些 IP。 - 否则,adapter 会通过 DNS-over-HTTPS(DoH)自动查询 Google DNS 和 Cloudflare DNS,以发现
api.telegram.org的其他 IP。 - DoH 返回的、与系统 DNS 结果不同的 IP 将用作回退。
- 如果 DoH 也被封锁,则使用硬编码的种子 IP(
149.154.167.220)作为最后手段。 - 一旦某个回退 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 会按顺序检查以下环境变量,使用第一个已设置的变量:
HTTPS_PROXYHTTP_PROXYALL_PROXYhttps_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 来实现更动态的用户授权方式。