Telegram 运维操作

管理 Telegram 论坛主题及 Bot API 相关操作。

前提条件

• Bot 必须在群组中拥有管理员权限，并启用 can_manage_topics 权限
• 从 OpenClaw 配置中获取 Bot Token：

  gateway action=config.get | jq -r '.result.parsed.channels.telegram.botToken'
  

创建主题

创建主题时，请严格按以下所有步骤执行：

1. 通过 Telegram Bot API 创建主题（返回 message_thread_id）
2. 设置主题图标——选择一个与主题用途相匹配的图标（参见图标参考表）
3. 选择相关技能——运行 openclaw skills list，仅选取状态为 ready 且契合该主题用途的技能
4. 编写系统提示词（system prompt）——为 Agent 提供关于该主题的上下文信息
5. 更新 OpenClaw 配置——将主题及其关联技能和系统提示词注册到配置中

步骤 1：通过 Bot API 创建

curl -X POST "https://api.telegram.org/bot/createForumTopic" 
  -H "Content-Type: application/json" 
  -d '{
    "chat_id": ,
    "name": "topic name"
  }'

返回 message_thread_id（即主题 ID），后续所有操作均需使用该值。

步骤 2：设置图标

curl -X POST "https://api.telegram.org/bot/editForumTopic" 
  -H "Content-Type: application/json" 
  -d '{
    "chat_id": ,
    "message_thread_id": ,
    "name": "topic name",
    "icon_custom_emoji_id": ""
  }'

步骤 3–5：配置 OpenClaw

通过 patch 方式更新配置，注册主题并指定其系统提示词：

gateway action=config.patch raw='{"channels":{"telegram":{"groups":{"":{"topics":{"":{"systemPrompt":"Topic-specific instructions"}}}}}}}'

主题配置继承自所属群组配置——仅需指定需要覆盖的字段。

请勿添加 skills 字段——省略该字段表示启用全部技能。仅当有明确需求限制主题能力时，才应显式指定受限技能列表。

会话密钥（Session Keys）

每个主题拥有独立隔离的 OpenClaw 会话：

agent:main:telegram:group::topic:

每个会话具备独立的对话历史、上下文窗口与压缩策略。

主题图标

完整图标 ID 列表详见 references/emoji-ids.md。

获取所有合法主题图标 sticker ID 的方法：

curl -X POST "https://api.telegram.org/bot/getForumTopicIconStickers"

归档主题

归档流程：重命名（添加 [ARCHIVED] 前缀）、设置文件夹图标、关闭主题，最后处理 OpenClaw 会话。

步骤 1：在 Telegram 中归档

使用归档脚本：

scripts/archive_topic.sh    "Current Topic Name"

该脚本将执行以下操作：

• 重命名为 [ARCHIVED] Current Topic Name
• 设置 📁 文件夹图标（ID：5357315181649076022）
• 关闭主题（禁止发送新消息）

步骤 2：导出并删除 OpenClaw 会话

# 将会话历史导出至 sessions 归档目录
openclaw sessions history 'agent:main:telegram:group::topic:' > ~/.openclaw/agents/main/sessions/archive/-.md

# 删除会话（手动操作 —— 从 sessions.json 中移除条目，并删除对应 transcript 文件）
# 会话密钥：agent:main:telegram:group::topic:

步骤 3：清理配置（可选）

若该主题曾配置过自定义参数，可将其从 OpenClaw 配置中彻底移除：

gateway action=config.patch raw='{"channels":{"telegram":{"groups":{"":{"topics":{"":null}}}}}}'

限制说明

Telegram Bot API 不提供 getForumTopicInfo 方法。 无法通过 thread ID 查询主题名称。

可行的变通方案：

1. 缓存来自 forum_topic_created 事件的主题名称
2. 在本地配置中维护主题 ID 与名称的映射关系
3. 监听主题创建时的系统服务消息