30秒让AI Agent接入Telegram：Caspian快速上手教程
30秒让AI Agent接入Telegram：Caspian快速上手教程
Caspian 是一个开源的 AI Agent 通信 SDK，能让你的 AI Agent 像"人"一样出现在 Telegram、Email、Slack、Discord、WhatsApp、SMS 等用户日常使用的聊天通道里。它提供 Python 和 TypeScript 双语言客户端，把最繁琐的 Webhook 验签、消息归一化、会话线程、重连等脏活全部封装好——你只需要写一个处理函数，Agent 就能开始收发消息。本文带你用 30 秒跑通第一个 Telegram 机器人。
一、为什么需要 Caspian？
自己接一个 Telegram Bot 不难，难的是长期维护：签名校验、消息去重、并发会话排队、不同平台的 payload 差异、断线重连……开源社区统计显示，大型 Agent 框架平均要花 8%–15% 的 issue 精力在"通道管道"上。
Caspian 的思路是：通道只是传输层，不是身份。所有通道的消息进入统一的 Thread / Message 模型，你写的同一个 handler 可以在 Telegram、Email、Slack 上通用。
核心能力一览：
- 🧵 声明式规则：用
@cx.on_message({...})按通道、命令、私聊/群聊过滤消息，规则可离线测试 - 🔐 Webhook 验签：Telegram secret、Slack 签名、Meta 签名全部内置，不匹配直接拒绝
- ☁️ Hosted / Self-host 双模式：用官方网关轮询，或自带 token 自建 Webhook，代码几乎不变
- ⌨️ 打字指示、流式回复、富消息：
thread.typing()、thread.stream()、按钮卡片一键发送
二、准备工作：3步拿到 Telegram Bot Token
- 在 Telegram 中搜索 @BotFather（官方机器人），发送
/newbot - 按提示给机器人起名字，得到形如
123456:ABC-DEF...的 Bot Token - 把 Token 保存为环境变量：
export TELEGRAM_BOT_TOKEN='123456:ABC-DEF...'
💡 Hosted 模式不需要公网地址，但仍然需要这个 BotFather Token（Caspian 不负责创建 Bot）。
三、30秒接入Telegram：最小可运行示例
一条命令安装 SDK（Python 3.10+ / Node 18+）：
pip install caspian-sdk # Python
npm install caspian-sdk # TypeScript / Bun
然后用不到 10 行代码启动你的 Agent：
from caspian import Caspian
cx = Caspian() # 默认走 Hosted 网关
cx.channels.add("telegram", bot_token="你的BOT_TOKEN")
@cx.on_message({"overlap": "queue", "ack": "收到，正在处理…"})
def handle(thread, msg, ctx):
thread.post(f"你说的是：{msg.text}")
cx.run() # 轮询网关事件，Ctrl+C 停止
运行后，在 Telegram 里私聊你的机器人发任意消息，几秒内就会收到回复。🎉 如果走 Hosted 模式，还需要从 Caspian Dashboard 获取 CASPIAN_API_KEY 并设置为环境变量。
仓库里提供了可直接运行的完整示例，handler 与进程文件分离、结构清晰：
- 可运行示例：bot.py（Self-host）、hosted.py（Hosted）
- 运行说明与环境变量清单：examples/telegram/README.md
- 所有通道示例索引：examples/README.md
四、两种接入模式怎么选？
| Self-host（自建） | Hosted（托管） | |
|---|---|---|
| 谁处理入站消息 | 你的 HTTP 服务 + cx.handle("telegram", ...) |
Caspian 网关，cx.run() 轮询 |
| 需要公网地址 | 需要（ngrok / cloudflared 等） | 不需要 |
| 额外配置 | webhook_url、可选 webhook_secret |
CASPIAN_API_KEY |
| 适用场景 | 数据不出内网、已有服务器 | 快速上线、零运维 |
两种模式共用同一套 handler 规则，切换时只需改 channels.add() 的参数：
# Self-host：自带 token + 公网 Webhook
cx.channels.add("telegram", via="self-host", bot_token="...",
webhook_url="https://your.server/telegram")
完整入口对照见 bot.py：Webhook 请求统一交给 cx.handle() 处理，验签、解析、分发全自动。
五、从 Telegram 到全通道：只加一行代码
Caspian 最爽的地方在于：Agent 只写一份逻辑，通道想加几个加几个。同一套 @cx.on_message 规则立即生效于所有通道：
cx.channels.add("email", display_name="Acme 客服")
cx.channels.add("telegram", bot_token="...")
cx.channels.add("slack", bot_token="...", signing_secret="...")
cx.run()
上图展示了 Agent 通过 Caspian 在 Email 通道自动应答的效果。目前已支持的通道包括：Telegram、Discord、Slack、Email、WhatsApp Business、Facebook Messenger、X、SMS/语音（Twilio）、iMessage、Linear，Hosted 模式还支持 Bluesky、Instagram DM 等更多通道。各通道的适配源码位于 packages/python/src/caspian/adapters/，TypeScript 版在 packages/typescript/src/adapters/。
六、CLI 命令行：不写代码也能管理通道
仓库内置了一个轻量 CLI（TypeScript + Bun），常用命令：
caspian init # 生成 API Key 到 .env
caspian channels add telegram # 添加 Telegram 通道
caspian call post --thread telegram:123:456 --text "shipping now"
caspian threads tail telegram:123:456 # 实时跟踪会话
完整命令清单见 packages/cli/README.md。
七、常见问题 FAQ
Q：必须用 Hosted 吗？有免费自部署方案吗？
A：可以完全 Self-host：pip install caspian-sdk 后用自己的 Bot Token + 任意公网 HTTPS 地址即可，SDK 本身开源（仓库 Apache-2.0 许可，PyPI 包为 MIT）。
Q：没有公网服务器怎么办？
A：本地开发可以用 ngrok / cloudflared 隧道暴露 Webhook；或者在 bot.py 中启用注释掉的 cx.poll("telegram") 长轮询模式。
Q：TypeScript 项目用哪个？
A：npm 包 caspian-sdk，API 与 Python 版一一对应（camelCase 风格），还支持 caspian-sdk/telegram 等按通道子路径导入，文档见 packages/typescript/README.md。
Q：Python 包 API 文档在哪里看？ A：完整 API 面见 packages/python/README.md，架构设计见 docs/architecture.md。
写在最后
接入一个通道是周末的事，维护它是终身的事。Caspian 把这层"通信管道"变成一个 SDK：channels.add() 一行加通道，on_message 一处写逻辑，thread.post() 一句话回复。现在就去 BotFather 建个机器人，让你的 AI Agent 开口说第一句话吧 🚀