Telegram
当你希望通过 Telegram 私信、群组或 topic 访问 Agent 时，可以连接 Telegram bot。
前提条件
- 已有 Cloud Agents Agent。
- 来自
@BotFather的 Telegram bot token。 - 如果需要群组访问，你需要有把 bot 加入目标群组的权限。
创建 bot
- 打开 Telegram，并与
@BotFather开始聊天。 - 发送
/newbot。 - 选择显示名称和全局唯一、以
bot结尾的用户名。 - 复制 bot token。
- 如果用于群组，并且 bot 需要接收普通群消息，请在 BotFather 的 bot 设置中关闭 Group Privacy。
连接到 Cloud Agents
- 打开 Settings -> Channels。
- 创建新渠道并选择 Telegram。
- 选择要接收消息的 Agent。
- 输入标签并粘贴 bot token。
- 创建渠道。
- 运行渠道测试。
渠道创建后，Cloud Agents 会自动注册 Telegram 投递地址。
推荐设置
| 设置 | 建议 |
|---|---|
| Mention only | 群组中建议开启，让 Agent 只在被 mention 时回复。 |
| Shared session | 默认关闭，除非群组中的所有人都应该共享同一段对话。 |
| Thread isolation | 对 topic 或 reply 较多的群组建议开启。 |
| Progress mode | 如果希望 Agent 工作时显示进度消息，使用 preview。 |
验证
打开渠道详情页并运行 Test。健康的渠道会显示 bot 身份，并确认 Telegram 投递已注册。
排查问题
- Token 测试失败：在 BotFather 中创建新 token，并更新渠道。
- 私信可用但群组消息不到达：在 BotFather 中关闭 Group Privacy，或 mention 这个 bot。
- 群组消息到了但被忽略：mention bot 用户名，或关闭 mention-only 模式。
- Bot 在错误上下文回复：对 topic 或 reply 较多的群组开启 thread isolation。