Back to Details

telegram-sync

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

telegram-sync

Telegram消息同步

Sync Telegram messages to local Markdown storage.
将Telegram消息同步到本地Markdown存储。

Trigger Phrases

触发指令

  • "sync Telegram"
  • "pull from Telegram"
  • "fetch Telegram messages"
  • "download Telegram history"
  • "telegram sync"
  • "sync my Telegram DMs"
  • "sync Telegram"
  • "pull from Telegram"
  • "fetch Telegram messages"
  • "download Telegram history"
  • "telegram sync"
  • "sync my Telegram DMs"

Description

工具说明

This skill downloads messages from Telegram groups and DMs to local Markdown files. Messages are stored in an LLM-friendly format that can be easily read and analyzed.
DMs are synced by default. Use 
--no-dms
to sync groups only.
该工具可将Telegram群组和私信（DMs）中的消息下载到本地Markdown文件中。消息会以LLM友好的格式存储，便于读取和分析。
默认同步私信（DMs）。使用
--no-dms
参数仅同步群组。

Usage

使用方法

Basic Sync (Groups + DMs)

基础同步（群组+私信）

Sync all (groups + DMs, last 7 days):
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py
Sync groups only (exclude DMs):
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --no-dms
同步全部内容（群组+私信，最近7天）：
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py
仅同步群组（排除私信）：
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --no-dms

Sync Specific Group

同步指定群组

bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890

Sync Specific DM

同步指定私信

bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --dm 123456789
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --dm 123456789

Time Range

时间范围

Sync last 30 days:
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --days 30
Full sync (ignore previous state):
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --full
同步最近30天的内容：
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --days 30
完全同步（忽略之前的同步状态）：
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --full

Forum Topics

论坛话题

Sync specific topic in a forum group:
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890 --topic 5
同步论坛群组中的指定话题：
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890 --topic 5

Custom Limits

自定义限制

Sync with custom message limit for groups:
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --days 30 --limit 5000
Sync with custom DM limit (default is 100 for privacy):
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --dm-limit 500
为群组设置自定义消息数量限制进行同步：
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --days 30 --limit 5000
为私信设置自定义消息数量限制（默认100条，出于隐私考虑）：
bash
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --dm-limit 500

Message Limits

消息数量限制

Group Limit (
--limit
)

群组限制（
--limit
）

  • Default: 2000 (configurable in 
    config/agents.yaml
    )
  • Use higher limits for longer lookback periods
  • Example: 
    --days 90 --limit 10000
    for 90-day archive
  • 默认值：2000（可在
    config/agents.yaml
    中配置）
  • 对于更长的回溯周期，可设置更高的限制
  • 示例：
    --days 90 --limit 10000
    用于90天的归档

DM Limit (
--dm-limit
)

私信限制（
--dm-limit
）

  • Default: 100 (privacy-conscious default)
  • Lower than group limit by design
  • Increase manually if needed: 
    --dm-limit 500
  • 默认值：100（出于隐私保护的默认设置）
  • 设计上默认值低于群组限制
  • 如需增加可手动设置：
    --dm-limit 500

Sync Modes

同步模式

Incremental Sync (default)

增量同步（默认）

  • Only fetches messages newer than the last sync
  • Fast and efficient for regular updates
  • Uses the 
    last_message_id
    from sync state
  • 仅获取比上次同步更新的消息
  • 快速高效，适合定期更新
  • 使用同步状态中的
    last_message_id
    进行追踪

Full Sync (--full)

完全同步（--full）

  • Ignores previous sync state
  • Downloads all messages within the date range
  • Use when you want a fresh start
  • 忽略之前的同步状态
  • 下载指定日期范围内的所有消息
  • 适合需要重新开始同步的场景

Output

输出路径

Groups

群组消息

Group messages are saved to:
data/{group_id}-{slug}/messages.md
data/{group_id}-{slug}/sync_state.yaml
data/{group_id}-{slug}/group.yaml
For forum groups with topics:
data/{group_id}-{slug}/{topic_name}/messages.md
群组消息将保存至：
data/{group_id}-{slug}/messages.md
data/{group_id}-{slug}/sync_state.yaml
data/{group_id}-{slug}/group.yaml
对于包含话题的论坛群组：
data/{group_id}-{slug}/{topic_name}/messages.md

DMs

私信消息

DM messages are saved to a separate directory:
dms/telegram/{user_id}-{name}/messages.md
dms/telegram/{user_id}-{name}/sync_state.yaml
dms/telegram/{user_id}-{name}/user.yaml
dms/telegram/manifest.yaml
私信消息将保存至单独的目录：
dms/telegram/{user_id}-{name}/messages.md
dms/telegram/{user_id}-{name}/sync_state.yaml
dms/telegram/{user_id}-{name}/user.yaml
dms/telegram/manifest.yaml

Rate Limiting

速率限制

Telegram has strict rate limits. The sync tool:
  • Adds delays between requests (100ms minimum)
  • Handles FloodWait errors automatically
  • Shows progress during sync
If rate limited, you'll see the wait time and can retry later.
Telegram有着严格的速率限制。同步工具会：
  • 在请求之间添加延迟（最低100毫秒）
  • 自动处理FloodWait错误
  • 同步过程中显示进度
如果被速率限制，你会看到等待时间，稍后可重试。

Message Format

消息格式

markdown
undefined
markdown
undefined

2026-01-06

2026-01-06

10:30 AM - @alice (123456)

10:30 AM - @alice (123456)

Hello everyone!
大家好！

10:31 AM - @bob (789012)

10:31 AM - @bob (789012)

↳ replying to @alice: Hey there!
[photo: vacation.jpg (1.2MB)]
Reactions: heart 5 | thumbsup 3
undefined
↳ 回复@alice： 嘿！
[photo: vacation.jpg (1.2MB)]
互动反馈：heart 5 | thumbsup 3
undefined

Exit Codes

退出码

  • 0
    - Success
  • 1
    - Authentication error
  • 2
    - Group not found or permission denied
  • 3
    - Rate limited
  • 0
    - 成功
  • 1
    - 认证错误
  • 2
    - 群组未找到或权限被拒绝
  • 3
    - 被速率限制

Troubleshooting

故障排除

"Could not find the input entity" Error

「无法找到输入实体」错误

Error message:
Could not find the input entity for PeerUser(user_id=...) (PeerUser)
What this means: Telethon (the Telegram library) doesn't have this group cached locally. It needs to know the group's "access hash" which is typically cached when you interact with the group.
Solutions (try in order):
  1. Run telegram-list first to refresh the entity cache:
    bash
    python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py
    This iterates through all your dialogs and caches the entities.
  2. Use the exact ID from telegram-list output:
    bash
    # First, list groups to get correct IDs
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py

# Then sync using the ID shown
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group <ID_FROM_LIST>
  3. Open the group in Telegram app:
    • Open the Telegram desktop or mobile app
    • Navigate to the group you want to sync
    • Send a message or just open the chat
    • This forces Telegram to cache the entity
    • Then retry the sync
  4. For supergroups/channels: Make sure you're using the correct ID format. Supergroup IDs are typically positive integers (not negative).
错误信息：
Could not find the input entity for PeerUser(user_id=...) (PeerUser)
错误含义： Telethon（Telegram开发库）在本地没有缓存该群组的信息。它需要获取群组的「访问哈希值」，通常在你与群组互动时会自动缓存。
解决方案（按顺序尝试）：
  1. 先运行telegram-list刷新实体缓存：
    bash
    python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py
    该命令会遍历所有对话并缓存实体信息。
  2. 使用telegram-list输出中的准确ID：
    bash
    # 首先，列出群组以获取正确的ID
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_list.py

# 然后使用获取到的ID进行同步
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group <ID_FROM_LIST>
  3. 在Telegram应用中打开群组：
    • 打开Telegram桌面或移动应用
    • 导航到你想要同步的群组
    • 发送一条消息或仅打开聊天窗口
    • 这会强制Telegram缓存该实体信息
    • 然后重试同步
  4. 对于超级群组/频道： 确保使用正确的ID格式。超级群组ID通常是正整数（非负数）。

"No group specified" Error

「未指定群组」错误

Error message:
No group specified and no default group configured.
Solution: Either specify a group ID or set a default:
bash
undefined
错误信息：
No group specified and no default group configured.
解决方案： 要么指定群组ID，要么设置默认群组：
bash
undefined

Option 1: Specify group directly

选项1：直接指定群组

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_sync.py --group 1234567890

Option 2: Set a default group

选项2：设置默认群组

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_init.py --group 1234567890
undefined
python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_init.py --group 1234567890
undefined

Permission Denied (Exit Code 2)

权限被拒绝（退出码2）

Possible causes:
  • You're not a member of the group
  • The group is private
  • You've been banned from the group
  • Admin permissions are required
Solution: Check your membership status in the Telegram app.
可能原因：
  • 你不是该群组的成员
  • 该群组是私有群组
  • 你已被移出该群组
  • 需要管理员权限
解决方案： 在Telegram应用中检查你的成员身份状态。

Rate Limited (Exit Code 3)

被速率限制（退出码3）

Error message:
Rate limited: Wait X seconds.
Solution: Wait the specified time before retrying. Telegram rate limits are strict and cannot be bypassed.
错误信息：
Rate limited: Wait X seconds.
解决方案： 等待指定的时间后重试。Telegram的速率限制非常严格，无法绕过。

Related Skills

相关工具

  • telegram-init
    - Initialize Telegram connection
  • telegram-list
    - List groups and topics
  • telegram-read
    - Read synced messages
  • telegram-init
    - 初始化Telegram连接
  • telegram-list
    - 列出群组和话题
  • telegram-read
    - 读取已同步的消息