专业Telegram富文本消息编排

OpenClaw官方Telegram消息格式化技能，通过Bot API发送富文本HTML消息，支持自动分片与错误回退，适合需要结构化通知的自动化场景。

基本信息

• 技能名称?telegram-compose
• 中文名称?专业Telegram富文本消息编排
• 作者?tmchow
• 分类?专业技能
• 版本?v1.0.4
• 标签?content-media, automation, api, productivity, operations

使用方法

使用说明
核心用法
telegram-compose 是一个声明式子代理技能，专为主会话代理自动调用而设计。当需要发送超过3行或包含结构化数据（列表、统计、章节、报告）的Telegram消息时，主代理会将其作为 Haiku 子代理启动。该技能负责将原始内容转换为视觉层次分明的 HTML 格式消息，通过 Telegram Bot API 直接投递。
使用流程遵循严格的决策规则：短回复（ sessions_spawn 启动子代理，传入 bot 账户名、聊天ID、线程ID（可选）及原始内容。子代理读取 SKILL.md 中的格式化规则，应用 HTML 标签、转义特殊字符、检查长度限制（4096字符），必要时按章节边界分片发送，最终通过 curl 调用 api.telegram.org 完成投递。
显著优点
专业化消息呈现 ：内置完整的 HTML 格式化规范，包括粗体、斜体、下划线、删除线、代码块、可展开引用块、剧透标签等，使通知具备专业视觉层次。特别针对移动端优化，禁止使用 > 展示统计数据，改用 emoji + 粗体 + 分隔符的流动布局，确保在小屏幕上可读。
智能内容处理 ：自动处理消息长度超限（4096字符），按章节边界智能分片，添加 "(continued)" 续接标识，并插入1秒延迟避免频率限制。内置完善的错误处理机制，包括 HTML 解析失败时自动降级为纯文本、线程不存在时回退到 General 话题、速率限制时自动重试。
安全架构设计 ：Bot Token 从 OpenClaw 配置文件读取，绝不硬编码；账户名由调用者显式指定，禁止子代理自动选择或遍历账户，避免误发风险。权限声明精确匹配实际功能（仅 exec 执行 curl、Read 读取配置），网络访问限定单一域名。
零依赖轻量化 ：纯声明式配置，无 npm/pip 等第三方包依赖，仅依赖系统标准工具 jq 和 curl，部署简单可靠。
潜在缺点与局限性
平台绑定限制 ：专为 Telegram 设计，无法直接迁移至其他消息平台（如 Slack、Discord、企业微信）。若需多平台支持，需额外开发适配层。
配置前置要求 ：依赖 OpenClaw 生态的特定配置文件结构（ ~/.openclaw/openclaw.json 或 ~/.openclaw/clawdbot.json ），且需预先配置 channels.telegram.accounts. .botToken 。对于非 OpenClaw 用户或配置管理不规范的环境，存在使用门槛。
HTML 转义复杂度 ：要求严格的三步转义顺序（ & → < → > ），内容中的特殊字符（如 "R&D"、"Q&A"）若处理不当会导致消息发送失败。虽然具备降级机制，但格式化丢失会影响专业呈现效果。
子代理通信开销 ：每次实质性消息触发一次 Haiku 子代理启动，对于高频、低延迟场景（如实时告警流）可能引入不必要的延迟和资源消耗。短消息直接发送与长消息子代理化的分支逻辑增加了主代理的决策复杂度。
适合的目标群体
运维与 SRE 团队 ：需要发送结构化的系统告警、状态报告、部署通知
产品经理与项目管理者 ：定期推送项目进度简报、优先级列表、会议纪要
数据分析师与研究员 ：分发数据摘要、统计洞察、研究报告的可视化摘要
自动化工作流开发者 ：构建需要富文本通知的 CI/CD、监控、ETL 流水线
Telegram 社区运营者 ：管理大型群组/频道，需要专业格式的公告、活动通知
使用风险
配置文件安全 ：Bot Token 存储于本地 JSON 文件，需确保文件权限（建议 600）防止未授权读取。多账户场景下，调用者必须显式指定账户名，配置错误可能导致消息发送至错误聊天。
API 依赖与可用性 ：完全依赖 Telegram Bot API（api.telegram.org）的可用性。Telegram 服务中断、网络封锁或 API 变更将直接影响功能。建议关键场景配置备用通知渠道。
消息长度与频率 ：虽然内置分片和速率限制处理，但极端高频场景（如每秒数十条消息）仍可能触发 Telegram 的滥用检测。建议对非紧急通知实施批量聚合或延迟队列。
HTML 格式兼容性 ：Telegram 客户端对 HTML 标签的支持存在版本差异，老旧客户端可能无法正确渲染 > 等新特性。关键消息建议测试目标用户群体的客户端版本分布。