telegram-ops

用于论坛管理的 Telegram Bot API 操作。用于创建/编辑/存档论坛主题、设置主题图标、通过 Bot API 管理 Telegram 组。在存档频道/主题时使用。需要 OpenClaw 配置中的机器人令牌。

# Telegram Ops

Manage Telegram forum topics and Bot API operations.

## Prerequisites

- Bot must be admin in the group with `can_manage_topics` permission
- Get the bot token from OpenClaw config:
  ```bash
  gateway action=config.get | jq -r '.result.parsed.channels.telegram.botToken'
  ```

## Creating a Topic

When creating a topic, follow all of these steps:

1. **Create the topic** via Telegram Bot API (returns `message_thread_id`)
2. **Set the icon** -- pick one that matches the topic's purpose (see [Icon Reference](#topic-icons))
3. **Choose relevant skills** -- run `openclaw skills list`, pick only `ready` skills that fit the topic's purpose
4. **Write a system prompt** -- give the agent context for what this topic is about
5. **Patch the OpenClaw config** -- register the topic with its skills and system prompt

### Step 1: Create via Bot API

```bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/createForumTopic" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": <GROUP_ID>,
    "name": "topic name"
  }'
```

Returns `message_thread_id` (the topic ID) -- you need this for all subsequent steps.

### Step 2: Set the Icon

```bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/editForumTopic" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": <GROUP_ID>,
    "message_thread_id": <TOPIC_ID>,
    "name": "topic name",
    "icon_custom_emoji_id": "<EMOJI_ID>"
  }'
```

### Step 3-5: Configure OpenClaw

Patch the config to register the topic with a system prompt:

```bash
gateway action=config.patch raw='{"channels":{"telegram":{"groups":{"<GROUP_ID>":{"topics":{"<TOPIC_ID>":{"systemPrompt":"Topic-specific instructions"}}}}}}}'
```

Topic configs inherit from the parent group -- only specify overrides.

**Do NOT add a `skills` key** -- omitting it means all skills are available. Only restrict skills if you have a specific reason to limit the topic's capabilities.

## Session Keys

Each topic gets its own isolated OpenClaw session:

```
agent:main:telegram:group:<GROUP_ID>:topic:<TOPIC_ID>
```

Each session has independent conversation history, context window, and compaction.

## Topic Icons

| Emoji | ID | Use Case |
|-------|-----|----------|
| ⚡ | `5312016608254762256` | Ops, speed, alerts |
| 💡 | `5312536423851630001` | Ideas, suggestions |
| 📰 | `5434144690511290129` | News, announcements |
| 🔥 | `5312241539987020022` | Hot topics, urgent |
| ❤️ | `5312138559556164615` | Community, love |
| 📝 | `5373251851074415873` | Notes, documentation |
| 🤖 | `5309832892262654231` | Bots, automation |
| 💬 | `5417915203100613993` | Chat, discussion |
| 📊 | `5350305691942788490` | Stats, analytics |
| 🎯 | `5418085807791545980` | Goals, targets |

See `references/emoji-ids.md` for complete list.

To fetch all valid icon sticker IDs:
```bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/getForumTopicIconStickers"
```

## Archiving a Topic

Archive workflow: rename with `[ARCHIVED]` prefix, set folder icon, close topic, then handle the OpenClaw session.

### Step 1: Archive in Telegram

Use the archive script:
```bash
scripts/archive_topic.sh <TOKEN> <GROUP_ID> <TOPIC_ID> "Current Topic Name"
```

This will:
- Rename to `[ARCHIVED] Current Topic Name`
- Set the 📁 folder icon (`5357315181649076022`)
- Close the topic (locks it from new messages)

### Step 2: Export and Delete OpenClaw Session

```bash
# Export session history to the sessions archive folder
openclaw sessions history 'agent:main:telegram:group:<GROUP_ID>:topic:<TOPIC_ID>' > ~/.openclaw/agents/main/sessions/archive/<topic-name>-<date>.md

# Delete the session (manual - remove from sessions.json and delete transcript)
# Session key: agent:main:telegram:group:<GROUP_ID>:topic:<TOPIC_ID>
```

### Step 3: Clean Up Config (Optional)

Remove the topic from OpenClaw config if it had custom settings:
```bash
gateway action=config.patch raw='{"channels":{"telegram":{"groups":{"<GROUP_ID>":{"topics":{"<TOPIC_ID>":null}}}}}}'
```

## Limitations

**No `getForumTopicInfo` method exists.** Cannot query topic name by thread ID.

Workarounds:
1. Cache names from `forum_topic_created` events
2. Store mapping in local config
3. Monitor topic creation service messages

---

## 中文说明

# Telegram Ops

管理 Telegram 论坛主题和 Bot API 操作。

## 前提条件

- 机器人必须是组内管理员，并具有 `can_manage_topics` 权限
- 从 OpenClaw 配置中获取机器人令牌：
  ```bash
  gateway action=config.get | jq -r '.result.parsed.channels.telegram.botToken'
  ```

## 创建主题

创建主题时，请遵循以下所有步骤：

1. **创建主题** —— 通过 Telegram Bot API（返回 `message_thread_id`）
2. **设置图标** —— 选择一个与主题用途相符的图标（见 [图标参考](#topic-icons)）
3. **选择相关技能** —— 运行 `openclaw skills list`，仅挑选符合主题用途的 `ready` 技能
4. **编写系统提示词** —— 为代理提供该主题相关的上下文
5. **修补 OpenClaw 配置** —— 将主题连同其技能和系统提示词一起注册

### 步骤 1：通过 Bot API 创建

```bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/createForumTopic" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": <GROUP_ID>,
    "name": "topic name"
  }'
```

返回 `message_thread_id`（主题 ID）—— 后续所有步骤都需要它。

### 步骤 2：设置图标

```bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/editForumTopic" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": <GROUP_ID>,
    "message_thread_id": <TOPIC_ID>,
    "name": "topic name",
    "icon_custom_emoji_id": "<EMOJI_ID>"
  }'
```

### 步骤 3-5：配置 OpenClaw

修补配置，将主题连同系统提示词一起注册：

```bash
gateway action=config.patch raw='{"channels":{"telegram":{"groups":{"<GROUP_ID>":{"topics":{"<TOPIC_ID>":{"systemPrompt":"Topic-specific instructions"}}}}}}}'
```

主题配置继承自父组 —— 只需指定要覆盖的项。

**请勿添加 `skills` 键** —— 省略它意味着所有技能均可用。仅在你有特定理由限制主题能力时才限制技能。

## 会话键

每个主题都有自己独立的 OpenClaw 会话：

```
agent:main:telegram:group:<GROUP_ID>:topic:<TOPIC_ID>
```

每个会话拥有独立的对话历史、上下文窗口和压缩。

## 主题图标

| Emoji | ID | 用例 |
|-------|-----|----------|
| ⚡ | `5312016608254762256` | 运维、速度、警报 |
| 💡 | `5312536423851630001` | 想法、建议 |
| 📰 | `5434144690511290129` | 新闻、公告 |
| 🔥 | `5312241539987020022` | 热门话题、紧急 |
| ❤️ | `5312138559556164615` | 社区、喜爱 |
| 📝 | `5373251851074415873` | 笔记、文档 |
| 🤖 | `5309832892262654231` | 机器人、自动化 |
| 💬 | `5417915203100613993` | 聊天、讨论 |
| 📊 | `5350305691942788490` | 统计、分析 |
| 🎯 | `5418085807791545980` | 目标、指标 |

完整列表见 `references/emoji-ids.md`。

要获取所有有效的图标贴纸 ID：
```bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/getForumTopicIconStickers"
```

## 存档主题

存档工作流：以 `[ARCHIVED]` 前缀重命名、设置文件夹图标、关闭主题，然后处理 OpenClaw 会话。

### 步骤 1：在 Telegram 中存档

使用存档脚本：
```bash
scripts/archive_topic.sh <TOKEN> <GROUP_ID> <TOPIC_ID> "Current Topic Name"
```

这会：
- 重命名为 `[ARCHIVED] Current Topic Name`
- 设置 📁 文件夹图标（`5357315181649076022`）
- 关闭主题（锁定，不再接收新消息）

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

```bash
# Export session history to the sessions archive folder
openclaw sessions history 'agent:main:telegram:group:<GROUP_ID>:topic:<TOPIC_ID>' > ~/.openclaw/agents/main/sessions/archive/<topic-name>-<date>.md

# Delete the session (manual - remove from sessions.json and delete transcript)
# Session key: agent:main:telegram:group:<GROUP_ID>:topic:<TOPIC_ID>
```

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

如果主题有自定义设置，从 OpenClaw 配置中移除它：
```bash
gateway action=config.patch raw='{"channels":{"telegram":{"groups":{"<GROUP_ID>":{"topics":{"<TOPIC_ID>":null}}}}}}'
```

## 限制

**不存在 `getForumTopicInfo` 方法。** 无法通过线程 ID 查询主题名称。

变通办法：
1. 从 `forum_topic_created` 事件中缓存名称
2. 在本地配置中存储映射
3. 监控主题创建的服务消息