Telegram Compose

通过 Telegram 直接 API，以 HTML 格式构建并发送富文本、高可读性的消息。

该技能的调用方式

本技能由主会话代理（main session agent）自动调用。 其他技能无需感知或依赖此技能。

决策规则（供主会话代理使用）

在向 Telegram 发送消息前，请检查：

• 简短回复（少于 3 行，无结构）： 直接通过 OpenClaw 的 message 工具发送。完成。
• 实质性内容（超过 3 行，或含列表/统计/章节/报告等结构）： 将本技能作为子代理（sub-agent）启动。

子代理的启动方式

主会话代理调用 sessions_spawn，参数如下：

sessions_spawn(
  model: "claude-haiku-4-5",
  task: "<任务内容 — 见下方模板>"
)

任务模板：

阅读 {baseDir}/SKILL.md 中的 telegram-compose 技能文档，了解格式规范，然后将以下内容格式化并发送至 Telegram。

Bot 账户：（例如 "main"；必须与 channels.telegram.accounts 中的键名完全匹配）
Chat ID：
Thread ID：（如非论坛/主题类聊天，请省略此行）

待格式化内容：
---
<原始内容在此>
---

发送成功后，仅返回 message_id；失败则返回错误详情。请勿在响应中包含已格式化的消息正文——它已被直接发送至 Telegram。

重要： 调用方必须明确指定所用 Bot 账户。子代理不得自行选择或遍历账户。

关键： 子代理的启动声明（announcement）将回传至主会话代理，而非 Telegram。因此，主会话代理在启动子代理后应立即回复 NO_REPLY，以防重复发送。子代理实际通过 curl 请求完成 Telegram 消息投递。

子代理接收的输入

1. 技能路径（Skill path） —— 用于读取格式规范
2. Bot 账户名（Bot account name） —— 指定使用的 Telegram Bot 账户（必须由调用方显式提供，禁止自动选择）
3. Chat ID —— 消息目标聊天 ID
4. Thread ID —— 如为论坛/主题类聊天，则提供对应话题 ID
5. 原始内容（Raw content） —— 待转换为富文本消息的未格式化文本或数据

凭证（Credentials）

Bot Token： 存储于 OpenClaw 配置文件中，路径为 channels.telegram.accounts..botToken。

账户名始终由调用方提供。 禁止自动选择或遍历账户。

# 自动检测配置路径
CONFIG=$([ -f ~/.openclaw/openclaw.json ] && echo ~/.openclaw/openclaw.json || echo ~/.openclaw/clawdbot.json)

# ACCOUNT 由调用方提供（例如 "main"）
# 在提取 token 前，需先验证账户是否存在
ACCOUNT=""
BOT_TOKEN=$(jq -r ".channels.telegram.accounts.$ACCOUNT.botToken" "$CONFIG")

if [ "$BOT_TOKEN" = "null" ] || [ -z "$BOT_TOKEN" ]; then
  echo "ERROR: 配置中未找到账户 '$ACCOUNT'，或其 botToken 字段为空"
  exit 1
fi

发送流程

CONFIG=$([ -f ~/.openclaw/openclaw.json ] && echo ~/.openclaw/openclaw.json || echo ~/.openclaw/clawdbot.json)
# ACCOUNT 由调用方提供 —— 禁止自动选择
BOT_TOKEN=$(jq -r ".channels.telegram.accounts.$ACCOUNT.botToken" "$CONFIG")

# 不含话题线程（普通聊天）
curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" 
  -H "Content-Type: application/json" 
  -d "$(jq -n 
    --arg chat "$CHAT_ID" 
    --arg text "$MESSAGE" 
    '{
      chat_id: $chat,
      text: $text,
      parse_mode: "HTML",
      link_preview_options: { is_disabled: true }
    }')"

# 含话题线程（forum/topic 聊天）
curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" 
  -H "Content-Type: application/json" 
  -d "$(jq -n 
    --arg chat "$CHAT_ID" 
    --arg text "$MESSAGE" 
    --argjson thread $THREAD_ID 
    '{
      chat_id: $chat,
      text: $text,
      parse_mode: "HTML",
      message_thread_id: $thread,
      link_preview_options: { is_disabled: true }
    }')"

格式规范

支持的 HTML 标签

粗体  斜体  下划线  删除线
等宽字体  
代码块
点击展开隐藏内容
引用块
默认折叠的引用块
超链接
通过 ID 提及用户

转义规则

仅对纯文本内容（不包括 HTML 标签内部）中的下列字符进行转义：

• & → &（务必最先执行，避免双重转义）
• < → <
• > → >

常见陷阱：含 & 的文本（如 “R&D”、“Q&A”）若未转义，将导致 HTML 解析失败。

结构模式

EMOJI 全大写标题

标签: 值
标签: 值

章节标题

• 列表项
• 另一项

关键引述或摘要

详细信息

此处为隐藏内容...
长篇细节请置于 expandable 引用块中。

操作链接 →

样式规范

1. 伪标题（Faux headings）： 使用 EMOJI CAPS TITLE 格式，并在其后插入空行
2. Emoji 使用： 每条消息限用 1–3 个 emoji，作为视觉锚点，非装饰用途
3. 空白行： 各逻辑区块之间必须用空行分隔
4. 长内容处理： 使用

   折叠展示

5. 链接排版： 单独成行，末尾加箭头： 链接文字 →

示例

状态更新：

📋 任务已完成

任务: 部署 v2.3
状态: ✅ 已完成
耗时: 12 分钟

所有健康检查均已通过。

告警：

⚠️ 需立即关注

问题: API 调用频率已达限额的 90%
建议操作: 审查当前用量

查看控制台 →

列表：

✅ 优先事项

• 审核 PR #234 — 已完成
• 完成文档 — 进行中
• 部署预发布环境

共 3 项，已完成 2 项

移动端友好的数据展示

切勿对统计信息、摘要或可视化布局使用

 标签。 
 使用等宽字体且在移动端严重换行，破坏对齐和树形符号渲染。仅将 
 用于真实代码或命令输出。

结构化数据推荐使用 emoji + bold + 分隔符组合：
❌ BAD（移动端换行错乱）:
├─ 🟠 Reddit  32 threads │ 1,658 pts
└─ 🌐 Web     8 pages


✅ GOOD（自然流式排版）:
🟠 Reddit: 32 threads · 1,658 pts · 625 comments
🔵 X: 22 posts · 10,695 likes · 1,137 reposts
🌐 Web: 8 pages (supplementary)
🗣️ 热门声量来源: @handle1 · @handle2 · r/subreddit

其他常用模式：
记录卡片（Record cards）：
Ruby
生日：6 月 16 日 · 年龄：11

Rhodes
生日：10 月 1 日 · 年龄：8

项目符号列表（Bullet lists）：
• hzl-cli: 1.12.0
• skill: 1.0.6


长度限制与分片策略

消息最大长度： 4,096 字符
媒体 caption 最大长度： 1,024 字符

若格式化后消息超出 4,096 字符：

按逻辑章节边界拆分（即 HEADING 块之间的空行处）
每一片段必须是合法 HTML（严禁在 HTML 标签内部截断）
按顺序逐片发送，片间间隔 1 秒
首片保留完整标题；后续片段开头添加延续标识：(continued)


错误处理
若 Telegram API 返回错误：



错误类型
应对措施



Bad Request: can't parse entities
HTML 格式非法。移除全部 HTML 标签，以纯文本重发。


Bad Request: message is too long
按上述分片规则拆分后重试。


Bad Request: message thread not found
移除 message_thread_id 参数重试（消息将发送至 General 频道）。


Too Many Requests: retry after X
等待 X 秒后重试一次。


其他任意错误
原样上报错误详情；不再重试。


降级规则（Fallback rule）： 若 HTML 格式化连续失败两次，则改以纯文本发送，确保送达优先于格式美观。

子代理执行核对清单
作为子代理运行时，请严格遵循以下步骤：

解析任务 —— 提取 Bot 账户名、Chat ID、Thread ID（如有）、技能路径及原始内容
读取本 SKILL.md —— 加载全部格式规范
格式化内容 —— 应用 HTML 标签、结构模式、样式规范及移动端友好数据排版
转义特殊字符 —— 仅对文本内容执行：先 &，再 <，最后 >（HTML 标签内不转义）
检查长度 —— 若超过 4,096 字符，按章节边界进行分片
获取 Bot Token —— 自动探测配置路径，按指定账户名提取 token（若未找到则报错退出）
发起 curl 请求 —— 根据是否含 Thread ID 选用对应模板
校验响应 —— 解析 curl 输出，确认 "ok": true
错误处理 —— 严格依照上表定义的错误响应策略执行
结果上报 —— 成功则返回 message_id；失败则返回完整错误详情