telegram-alert

面向专业交易团队的多通道告警通知系统。支持Telegram多群组推送、复合触发条件、富媒体消息（图表/图片）、定时播报与团队协作功能。适用于需要消息发送、通知推送、通信集成的场景。不适用于垃圾信息群发。Use when 用户需要telegram-alert相关功能时使用。不适用于超出本技能能力范围的复杂需求。

天轰穿@thcjp

Install

openclaw skills install @thcjp/telegram-alert

Telegram告警专业版

专业版增强能力

能力	免费版	付费版
基础功能	支持	支持
多渠道消息批量发送	不支持	支持
消息模板与变量注入	不支持	支持
送达状态实时回调	不支持	支持
通信记录归档与检索	不支持	支持
消息频控与智能排队	不支持	支持

功能能力

PRO版功能增强对比

功能	免费版	PRO版
目标群组	单一	多群组同步
触发条件	单一条件	复合(AND/OR)
消息格式	基础Markdown	富媒体+按钮
通知通道	仅Telegram	+钉钉/企微/邮件
定时播报	基础定时	工作流自动化
告警去重	不支持	智能去重
优先级	不支持	3级优先级
历史分析	基础记录	统计与分析

复合触发条件

yaml

# PRO版支持复合逻辑
triggers:
  - name: "BTC突破+成交量放大"
    conditions:
      - ticker: BTC-USD
        metric: price
        operator: "above"
        value: 65000
      - ticker: BTC-USD
        metric: volume
        operator: "above"
        value: 1000000000
    logic: "AND"                    # AND 或 OR
# ...
  - name: "跌至支撑位或破前低"
    conditions:
      - ticker: AAPL
        metric: price
        operator: "below"
        value: 170
      - ticker: AAPL
        metric: price
        operator: "below"
        value: 165
    logic: "OR"

入门指引

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

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

应用场景

场景一：多群组信号分发

用户输入："把买入信号同时发到3个Telegram群"

bash

# 多群组推送
python3 （请参考skill目录中的脚本文件） broadcast \
  --message "买入信号: AAPL 突破阻力位180" \
  --chat-ids "@group1,@group2,@group3" \
  --priority high \
  --include-chart
# ...
# 输出：各群组发送状态
# [OK] @group1 - 发送成功
# [OK] @group2 - 发送成功
# [FAIL] @group3 - 发送失败（重试中）

场景二：复合触发告警

用户输入："BTC突破65000且成交量超过10亿时提醒"

bash

# 设置复合触发
python3 （请参考skill目录中的脚本文件） add \
  --name "BTC突破+量能" \
  --conditions "price:BTC-USD:above:65000,volume:BTC-USD:above:1000000000" \
  --logic AND \
  --channels "telegram,dingtalk" \
  --priority high
# ...
# 启动监控
python3 （请参考skill目录中的脚本文件） monitor --multi-channel

场景三：定时市场播报

用户输入："每天9点和15点发市场概况，带图表"

bash

# 设置定时播报
python3 （请参考skill目录中的脚本文件） add \
  --name "每日市场播报" \
  --times "09:00,15:00" \
  --message-type "market_summary" \
  --include-chart \
  --include-watchlist \
  --channels "telegram,dingtalk" \
  --chat-ids "@trading_team"

操作步骤

PRO版初始化

bash

# 依赖说明
pip install -r requirements_pro.txt
# ...
# 配置多通道
cp config_pro_template.yaml config_pro.yaml
# 填入各通道的凭证

常用命令

bash

# 多群组广播
python3 （请参考skill目录中的脚本文件） broadcast --message "信号" --chat-ids "@g1,@g2,@g3"
# ...
# 复合告警
python3 （请参考skill目录中的脚本文件） add --conditions "price:AAPL:above:180,volume:AAPL:above:100M" --logic AND
# ...
# 定时播报
python3 （请参考skill目录中的脚本文件） add --times "09:00,15:00" --message-type market_summary
# ...
# 告警历史分析
python3 （请参考skill目录中的脚本文件） stats --period 30d
python3 （请参考skill目录中的脚本文件） export --format excel

输入规范

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

输出规范

json

{
  "success": true,
  "data": {
    "message_id": "msg_20260728_001",
    "sent_channels": ["telegram"],
    "failed_channels": [],
    "metadata": {
      "template_used": "alert_pro",
      "priority": "high",
      "timestamp": "2026-07-28T10:30:00Z"
    }
  },
  "error": null
}

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

异常处置

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

安装与配置

运行环境

Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
操作系统: Windows / macOS / Linux
Python版本: 3.9+
网络: 需访问各通知通道API

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供
Python	运行时	必需	系统安装或conda环境
python-telegram-bot	Python库	必需	`pip install python-telegram-bot`
requests	Python库	必需	`pip install requests`
matplotlib	Python库	可选	`pip install matplotlib`（图表生成）
Jinja2	Python库	可选	`pip install jinja2`（消息模板）
psycopg2	Python库	可选	`pip install psycopg2-binary`（历史存储）

API Key 配置

服务	环境变量	是否必需	用途
Telegram Bot	`TELEGRAM_BOT_TOKEN`	必需	Telegram消息推送
钉钉	`DINGTALK_WEBHOOK`	可选	钉钉消息推送
企业微信	`WECOM_WEBHOOK`	可选	企微消息推送
邮件	`SMTP_HOST`等	可选	邮件通知

未配置的通道自动跳过，不影响已配置通道
所有凭证存储在本地配置文件

可用性分类

分类: MD+EXEC（Markdown指令+Python脚本执行）
说明: 多通道告警通知系统，支持复合触发与富媒体消息
PRO版特性: 多群组同步、复合触发、富媒体、多通道、告警去重、优先级管理
兼容性: 完全兼容免费版命令与配置，支持一键迁移

案例展示

PRO多通道配置

yaml

pro_config:
  channels:
    telegram:
      bot_token: "${TELEGRAM_BOT_TOKEN}"
      groups:
        - chat_id: "@trading_signals"
          name: "交易信号群"
          priority: high
        - chat_id: "@risk_alerts"
          name: "风险告警群"
          priority: critical
        - chat_id: "@market_summary"
          name: "市场概况群"
          priority: normal
# ...
    dingtalk:
      webhook: "${DINGTALK_WEBHOOK}"
      secret: "${DINGTALK_SECRET}"
# ...
    wechat_work:
      webhook: "${WECOM_WEBHOOK}"
# ...
    email:
      smtp_host: "${SMTP_HOST}"
      smtp_port: 587
      username: "${EMAIL_USER}"
      password: "${EMAIL_PASS}"
# ...
  alerts:
    deduplication:
      enabled: true
      window: 300                # 去重窗口（秒）
    priority:
      levels: [critical, high, normal, low]
      routing:
        critical: ["telegram", "dingtalk", "email"]
        high: ["telegram", "dingtalk"]
        normal: ["telegram"]
        low: ["telegram"]
# ...
    triggers:
      max_conditions: 10         # 单告警最大条件数
      logic: ["AND", "OR"]
      custom_scripts: true       # 支持自定义脚本
# ...
  scheduling:
    timezone: "Asia/Shanghai"
    max_schedules: 50
    retry_failed: true
# ...
  history:
    storage: "数据库"
    retention_days: 365
    analytics: true

问答集锦

Q1：支持哪些通知通道？

PRO版支持Telegram、钉钉、企业微信、飞书Webhook和邮件五种通道。可同时配置多个通道，告警按优先级自动路由.

Q2：复合触发条件如何工作？

当所有条件（AND）或任一条件（OR）满足时触发告警。支持价格、成交量、技术指标等多种指标的组合。每个告警最多支持10个条件.

Q3：告警去重如何工作？

PRO版在配置的去重窗口（默认5分钟）内，相同标的相同类型的告警只发送一次。避免因价格波动导致短时间内重复告警.

Q4：富媒体消息支持哪些内容？

支持发送图表（自动生成价格走势图）、图片、交互按钮（如"查看详情"、"确认交易"）。图表数据实时获取并渲染.

Q5：定时播报支持自定义内容吗？

支持。可通过自定义脚本生成播报内容，包括市场概况、持仓P&L、自选股变动等。支持Jinja2模板灵活定制消息格式.

错误恢复指南

错误场景(续)	原因	处理方式
LLM响应超时或无响应	网络延迟或模型负载过高	请求重试；确认Agent平台LLM服务正常
输入内容格式不正确	用户输入不符合skill预期格式	检查输入是否符合skill使用说明中的格式要求，参考示例章节
执行结果与预期不符	指令描述不够明确或上下文不足	提供更详细的指令描述，补充必要的上下文信息
命令执行失败	运行环境不满足要求或权限不足	确认运行环境符合依赖说明中的要求；检查命令权限设置

功能边界

Bot Token依赖: 必须配置有效的Telegram Bot Token才能使用核心功能
群组权限: Bot需被添加为目标群组成员并具有发送消息权限
API频率限制: Telegram API限制每秒30条消息，批量发送时自动排队
富媒体生成: 图表生成依赖matplotlib，未安装时降级为纯文本消息
历史存储: 历史记录功能依赖数据库，未配置时不影响告警功能
时区支持: 定时播报使用配置的时区，默认为Asia/Shanghai

安全规范

无硬编码密钥: 所有Bot Token、Webhook URL等凭证通过环境变量加载，不在代码中硬编码
无敏感信息泄露: 日志中对Token、Webhook等敏感字段进行脱敏处理
凭证存储安全: 配置文件建议加入.gitignore，避免泄露到版本控制系统
最小权限原则: Bot仅授予发送消息权限，不需要管理员权限
数据传输加密: 所有API调用使用HTTPS加密传输
无不可信外部调用: 仅调用用户配置的通知通道API，不发起未授权请求

安全风险防范

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

功能详解与边界条件

核心功能详解

多群组广播：支持同时向多个Telegram群组发送告警消息，各群组独立追踪发送状态。
复合触发条件：支持AND/OR逻辑组合多个触发条件，可基于价格、成交量、技术指标等。
富媒体消息：支持发送自动生成的价格图表、图片、交互按钮等富媒体内容。
多通道通知：除Telegram外，支持钉钉、企业微信、邮件等通道，按优先级自动路由。
告警去重：在配置的时间窗口内对相同标的的相同告警进行去重，避免重复打扰。
定时播报：支持按时间计划自动发送市场概况、持仓分析等定期报告。

边界条件

群组数量限制：单次广播最多支持50个群组。
消息长度限制：单条消息不超过4096个字符（Telegram API限制）。
触发条件限制：单个告警最多支持10个复合条件。
定时任务限制：最多支持50个定时任务。
去重窗口：默认300秒，可配置范围为60-3600秒。
优先级级别：支持critical、high、normal、low四个级别。
API频率：Telegram API限制每秒30条消息，超出自动排队。
历史保留期：历史记录默认保留365天。

性能指标

消息发送延迟：单条消息发送延迟<2秒。
多群组广播：10个群组广播完成时间<10秒。
触发检测精度：触发条件检测延迟<1秒。
系统可用性：系统可用性不低于99.5%。
错误率：消息发送错误率<0.1%。

差异化优势对比

与同类方案对比

功能	Telegram告警专业版	原生Telegram Bot	钉钉群机器人
多群组同步	支持，一次配置多群组推送	不支持，需逐个发送	不支持
复合触发条件	支持，AND/OR逻辑组合	不支持	不支持
富媒体消息	支持图表、图片、按钮	仅支持基础格式	仅支持基础Markdown
多通道路由	Telegram+钉钉+企微+邮件	仅Telegram	仅钉钉
告警去重	智能去重，可配置窗口	不支持	不支持
优先级管理	4级优先级自动路由	不支持	不支持
定时播报	支持自定义内容与模板	不支持	不支持
历史分析	支持，可导出Excel	不支持	不支持

独有功能组合

多通道智能路由：根据告警优先级自动选择通知通道，critical级别同时推送多通道，low级别仅推Telegram。
复合触发与去重结合：支持复杂的AND/OR触发条件组合，同时通过智能去重避免短时间内重复告警。
富媒体自动生成：自动获取实时市场数据并生成价格走势图表，无需人工截图。

诊断与修复

错误现象	可能原因	诊断步骤	解决方案
消息发送失败	群组ID错误或Bot权限不足	检查群组ID是否正确，确认Bot是否已加入群组并具有发送消息权限	修正群组ID，确保Bot权限
复合触发条件不工作	条件配置错误或逻辑错误	检查条件配置是否正确，逻辑符是否使用正确（AND/OR）	修正条件配置，确保逻辑符正确
富媒体消息无法生成	matplotlib未安装或配置错误	检查matplotlib是否已安装，确认配置文件中matplotlib路径正确	安装matplotlib，检查配置文件
定时任务未触发	定时任务配置错误或服务器时间错误	检查定时任务配置是否正确，确认服务器时间与实际时间一致	修正定时任务配置，同步服务器时间
网络连接问题	网络连接不稳定或API服务不可达	检查网络连接，确认API服务是否可达	恢复网络连接，确认API服务

创新亮点

效率提升量化分析

场景	Telegram告警专业版	传统方法	效率提升
多群组消息推送	同时向多个群组发送消息，无需逐个操作	逐个群组发送，效率低	10倍提升
复合触发条件	自动组合多个条件触发告警，无需手动检查	手动检查每个条件，效率低	5倍提升
富媒体自动生成	自动生成图表和图片，无需人工截图	人工截图，效率低	3倍提升
多通道智能路由	自动选择优选通知通道，无需手动切换	手动切换通道，效率低	2倍提升
告警去重	自动去重，避免重复打扰	手动去重，效率低	1.5倍提升

差异化对比

功能	Telegram告警专业版	竞品A	竞品B
多群组同步	支持，一次配置多群组推送	不支持	不支持
复合触发条件	支持，AND/OR逻辑组合	支持	不支持
富媒体消息	支持图表、图片、按钮	支持	支持
多通道路由	Telegram+钉钉+企微+邮件	仅支持Telegram	仅支持钉钉
告警去重	智能去重，可配置窗口	不支持	不支持
优先级管理	4级优先级自动路由	不支持	不支持
定时播报	支持自定义内容与模板	不支持	不支持
历史分析	支持，可导出Excel	不支持	不支持

功能介绍

自动化执行: 多通道交易告警系统，支持Telegram多群组推送、复合触发条件、富媒体消息与团队协作。
文件处理: 支持多种文件格式的读取、解析和写入操作
API集成: 通过标准化接口调用外部服务并处理响应
命令执行: 在安全沙箱中执行系统命令并收集结果

技术支持

Q1: Telegram告警专业版支持哪些输入格式？

A1: 多通道交易告警系统，支持Telegram多群组推送、复合触发条件、富媒体消息与团队协作。。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

效能分析

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

核心功能亮点

文件处理: 支持多种文件格式的读取、解析和写入操作
API集成: 通过标准化接口调用外部服务并处理响应
命令执行: 在安全沙箱中执行系统命令并收集结果

错误恢复方案

针对Telegram告警专业版使用中可能遇到的常见问题,提供以下排查方案:

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

Telegram告警专业版通用排查步骤

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

部署指引

配置API密钥: 在环境变量中设置对应的API Key
初始化连接: 使用提供的凭证建立API连接
调用接口: 传入必要参数执行API调用
准备文件: 确认文件路径正确且格式受支持
执行处理: 调用对应的处理函数
查看结果: 检查输出文件或返回数据
检查环境: 确认运行时和依赖已安装
执行命令: 使用正确的参数格式执行
查看输出: 检查命令输出和退出码

前置条件

已安装所需运行环境(参考依赖说明)
已获取必要的API密钥或访问凭证(如适用)
输入数据已准备就绪