Telegram Toolkit

专业版Telegram Bot工具，支持多机器人管理、多轮会话状态机、富媒体模板、消息队列削峰及Webhook监控与自动告警。

Install

openclaw skills install @thcjp/telegram-toolkit

核心功能: 本技能提供中文交互等能力。

核心功能: 本技能提供、运维告警、部署管理时使用、时使用等能力。

TG机器人工具(专业版)

专业版专属特性

能力	免费版	付费版
基础功能	支持	支持
TG机器人工具(专业版)多机器人管理	不支持	支持
多渠道消息批量发送	不支持	支持
消息模板与变量注入	不支持	支持
送达状态实时回调	不支持	支持
通信记录归档与检索	不支持	支持

能力清单

能力分类	免费版	专业版
对话管理	单轮命令	多轮状态机+上下文持久化
富媒体	纯文本	图片/视频/文件/按钮模板库
多Bot管理	单Bot	统一面板管理多Bot
消息发送	同步发送	队列削峰+批量+限流控制
Webhook监控	无	健康检查+告警+故障切换
国际化	无	多语言模板+语言自适应
优先支持	社区	工单优先响应

即学即用

确认运行环境满足依赖说明中的要求
在AI Agent对话中调用本技能,提供必要的输入参数
检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

典型场景

场景一：多轮客服对话（产品视角）

通过状态机编排"收集问题→分类→转人工→满意度回访"的多轮对话流程，上下文跨轮次持久化.

python

from telegram_toolkit import ProFeatures, StateMachine
# ...
pro = ProFeatures(token_env="TG_BOT_TOKEN")
# ...
sm = StateMachine()
sm.add_state("await_issue", prompt="请描述您遇到的问题")
sm.add_state("await_category", prompt="请选择问题分类：1.账单 2.功能 3.故障")
sm.add_transition("await_issue", "await_category", on="text_received")
sm.add_transition("await_category", "resolved", on="category_selected")
# ...
pro.register_conversation("/support", sm)

场景二：多Bot矩阵运营（运营视角）

通过统一面板管理客服Bot、通知Bot、营销Bot的配置、监控与消息统计，无需逐个切换.

python

pro.manage_bots([
    {"name": "客服Bot", "token_env": "SUPPORT_BOT_TOKEN"},
    {"name": "通知Bot", "token_env": "NOTIFY_BOT_TOKEN"},
    {"name": "营销Bot", "token_env": "MARKETING_BOT_TOKEN"}
])
pro.dashboard.start()  # 启动统一监控面板

场景三：高并发营销推送（营销视角）

将10万条营销消息入队，按Telegram限流规则自动节流发送，支持优先级与失败重试.

python

pro.broadcast(
    audience="subscribers.csv",
    template="templates/promo.html",
    rate_limit=25,            # 每秒25条（低于Telegram限制）
    priority="normal",
    retry_failed=True
)

场景四：富媒体通知（开发者视角）

通过模板库发送带Inline Keyboard按钮、图片、格式化文本的富媒体通知，提升信息可读性.

python

pro.send_template(
    chat_id=user_id,
    template="alert_with_buttons",
    context={
        "title": "部署完成",
        "detail": "服务v1.2.3已上线",
        "buttons": [
            {"text": "查看日志", "callback_data": "view_log"},
            {"text": "回滚", "callback_data": "rollback"}
        ]
    }
)

场景五：Webhook健康监控（运维视角）

持续监控Webhook健康状态，延迟超阈值自动告警，故障时自动切换到长轮询兜底.

python

pro.webhook_monitor(
    health_check_interval=60,        # 60秒检查一次
    latency_alert_ms=5000,          # 延迟超5秒告警
    auto_fallback_to_polling=True,  # Webhook故障自动切长轮询
    webhook_env="OPS_WEBHOOK"       # 告警地址
)

操作流程

优秀步：启用专业版功能

python

from telegram_toolkit import ProFeatures
# ...
pro = ProFeatures(token_env="TG_BOT_TOKEN")
pro.enable_message_queue(max_size=10000, rate_limit=25)
pro.webhook_monitor(auto_fallback_to_polling=True)

第二步：注册对话状态机

python

sm = pro.create_conversation("/onboarding")
sm.add_state("ask_name", prompt="请输入您的姓名")
sm.add_state("ask_email", prompt="请输入您的邮箱")
sm.add_state("done", prompt="注册完成！")
sm.add_transition("ask_name", "ask_email", on="text_received")
sm.add_transition("ask_email", "done", on="text_received")

第三步：发送富媒体模板

python

pro.send_template(chat_id, "welcome_card", context={"user": "张三"})

完整上手时间约120秒.

输入参数

参数名	类型	必填	说明
content	string	否	处理的内容输入
mode	string	否	处理模式, 可选值: json/text/markdown
style	string	否	输出风格, 参考 `references/style.md`

输出规范

json

{
  "success": true,
  "data": {
    "result": "处理结果",
    "status": "success",
    "metadata": {
    "metadata": {
      "template_used": "reviewer",
      "word_count": 0,
      "style": "专业"
    }
  },
  "error": null
}

输出模板参考: assets/output.json

异常应对

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux
网络: 需能访问 api.telegram.org
Python: 3.8+

依赖说明(补充)

依赖项	类型	是否必需	获取方式
requests	Python包	必需	`pip install requests`
Python	运行时	必需	python.org 官方下载
redis	Python包	可选	`pip install redis`（会话持久化）
sqlite3	Python模块	可选	Python标准库（会话持久化）
jinja2	Python包	可选	`pip install jinja2`（模板渲染）

API Key 配置

TG_BOT_TOKEN: 通过 @BotFather 获取，存入环境变量，禁止硬编码
多Bot Token: 每个Bot独立环境变量（如 SUPPORT_BOT_TOKEN、NOTIFY_BOT_TOKEN）
Webhook secret_token: 设置Webhook时生成，服务端校验请求头
OPS_WEBHOOK: 监控告警Webhook地址，通过环境变量配置

可用性分类

分类: MD+EXEC（）
说明: 基于Markdown的AI Skill，

案例展示

消息队列削峰

python

pro.queue_config(
    max_size=50000,           # 队列上限
    rate_limit=25,            # 每秒发送上限（Telegram限制约30/s）
    batch_size=25,            # 批量发送数
    retry_policy="exponential",  # 失败指数退避
    priority_levels=3         # 3级优先级
)

多Bot统一监控

python

pro.dashboard_config(
    metrics=["uptime", "msg_sent", "msg_failed", "active_users"],
    refresh_interval=30,
    alert_on_failure=True,
    webhook_env="OPS_WEBHOOK"
)

国际化配置

python

pro.i18n_config(
    default_lang="zh-CN",
    detect_user_lang=True,     # 从用户语言设置自动检测
    templates_dir="locales/"
)
# locales/zh-CN/welcome.json
# locales/en/welcome.json

常见疑问

Q1：状态机对话中途用户输入无关内容怎么办？

A：为每个状态设计fallback处理，当输入不匹配预期时提示用户正确输入或重置对话。可用sm.add_fallback(state, handler)配置.

Q2：批量推送时部分消息429失败如何重试？

A：专业版消息队列自带失败重试。429会按retry_after等待后重试，重试3次仍失败则记录到失败队列，可用pro.retry_failed()单独重发.

Q3：Webhook故障切换到长轮询会丢消息吗？

A：不会。切换前会先deleteWebhook，Telegram将未投递的更新保留在服务端，长轮询通过getUpdates的offset参数从断点继续拉取.

Q4：多Bot管理的Token如何安全存储？

A：每个Bot的Token存入独立环境变量（如SUPPORT_BOT_TOKEN、NOTIFY_BOT_TOKEN），专业版通过token_env参数引用，绝不落盘明文.

Q5：富媒体模板如何复用？

A：模板存为JSON文件放templates/目录，通过pro.send_template(chat_id, "template_name", context)渲染发送。不同Bot可共享模板目录.

Q6：国际化模板如何组织？

A：按语言代码建子目录：locales/zh-CN/、locales/en/。每语言下保持相同文件名结构，专业版根据用户语言设置自动选择对应模板.

Q7：消息队列积压怎么办？

A：(1) 检查rate_limit是否过低；(2) 评估是否为营销推送峰值，考虑分批错峰发送；(3) 提高队列max_size或增加并发worker；(4) 监控队列长度告警，超阈值触发降级.

Q8：对话上下文如何持久化？

A：专业版支持将会话状态持久化到本地SQLite或Redis。配置sm.persist(backend="sqlite", path="sessions.db")，Bot重启后可恢复未完成的对话.

Q9：Inline Keyboard按钮回调超时怎么办？

A：Telegram对callback_query无硬性超时，但用户体验上建议30秒内应答。专业版消息队列会优先处理callback应答，避免用户长时间等待.

Q10：专业版支持Telegram Mini App吗？

A：支持。专业版提供Mini App的Web App URL配置与web_app_data更新处理，可用于构建内嵌在Telegram中的Web应用交互.

功能边界

需要LLM支持
依赖Agent平台的LLM能力与运行环境配置
免费版功能受限，高级能力需升级专业版
处理能力受限于本地硬件资源

差异化分析

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
消息批量发送	10小时	2小时	8小时	95%
对话状态管理	2小时/轮次	0.5小时/轮次	1.5小时/轮次	100%
富媒体消息制作	1小时/条	15分钟/条	45分钟/条	98%
多机器人管理	1小时/机器人	10分钟/机器人	50分钟/机器人	100%
Webhook监控与告警	2小时/天	30分钟/天	1.5小时/天	100%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
功能全面性	高	低	中	高
操作便捷性	高	低	中	高
成本效益	高	低	中	高
扩展性	高	低	中	高
支持与维护	高	低	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
多机器人管理困难	需要手动管理多个机器人，效率低	所有机器人管理	提供统一管理面板	时间节约50%
富媒体消息制作复杂	制作富媒体消息需要专业工具和技能	所有富媒体消息制作	提供模板库和变量注入	制作效率提升98%
消息发送效率低	消息发送速度慢，影响用户体验	所有消息发送	消息队列削峰与批量发送	发送效率提升95%

诊断与修复

错误现象	可能原因	诊断步骤	解决方案
无法注册对话	配置参数错误	检查配置文档和参数设置	修正配置参数
无法发送消息	机器人Token错误	检查机器人Token是否有效	重新获取Token
消息发送失败	网络问题	检查网络连接	修复网络连接
Webhook无响应	配置错误	检查Webhook配置	修正配置
消息队列拥堵	消息量过大	检查消息量	调整队列大小或限流

安全忠告

[与「TG机器人工具(专业版)」相关的安全注意事项]
- 确保机器人Token安全，避免泄露。
- 定期更新机器人代码，修复安全漏洞。
- 对敏感数据进行加密处理。
- 限制机器人访问权限，避免未经授权的操作。
- 监控机器人行为，及时发现异常情况。

安全风险防范

风险项	等级	防护措施	验证方法
API密钥泄露	高	通过环境变量配置，禁止硬编码	定期检查代码和配置文件
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志

功能特点

自动化执行: 面向企业的Telegram Bot专业版，含对话状态机、富媒体模板、多机器人管理、消息队列与优先支持。
文件处理: 支持多种文件格式的读取、解析和写入操作
API集成: 通过标准化接口调用外部服务并处理响应
命令执行: 在安全沙箱中执行系统命令并收集结果

错误应对体系

针对"TG机器人工具(专业版)"使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置

"TG机器人工具(专业版)"通用排查步骤

检查输入参数: 确认所有必填参数已提供且格式正确
查看日志输出: 定位具体错误行和异常类型
验证环境配置: 确认依赖库版本和运行环境满足要求
逐步调试: 缩小问题范围,隔离故障模块

用户问题集锦

异常管理

针对"TG机器人工具(专业版)"使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置