ClawHub

TG-Crawler — Telegram 舆情采集工具

Other

Telegram 频道/群组舆情采集工具 v3.12。支持四种模式：hybrid（发现+回溯）、discover（仅频道发现）、backfill（仅消息回溯）、monitor（实时监控）。内置数据保留策略，自动清理过期数据，防止磁盘膨胀。

Install

openclaw skills install tg-crawler

版本历史

每次迭代更新此表，按时间倒序。

版本日期变更内容
v3.122026-06-05🔧 第五轮 Review 修复 (3 项)。P0: get_entity 短 FloodWait 重试后不回溯 (B16)、resume 误跳过 rate_limited/partial 频道 (B18)。P1: dry-run 过滤说明从 "backfill" 修正为 "discover" 关键词 (B17)。重构 _backfill_channels: get_entity 提取为重试包装器，移除笨重的内嵌 retry 逻辑
v3.112026-06-05🚀 实战 Review 修复 (10 项)。P0: YAML 追加改用 dump 全量重写 (B13)、get_entity FloodWait + ChannelPrivateError 专用 catch (B14)、run_hybrid discover 后 load_targets 失败兜底 (B15)。P1: YAML 写入后校验 + 失败回滚 (D10)、追加前 .bak 备份 (D11)、asyncio disconnect 先于 loop.close (D12)。P2: targets_common.yaml 自动修复脚本、短 FloodWait 分级处理
v3.102026-06-05🚀 三轮 Code Review 全面修复 (13 项)。P0: title 二次过滤/discover 阶段2.5 用生态词、_parse_channel_from_link UnboundLocalError、run_backfill 缺 rules→TypeError。P1: FloodWaitError 全局覆盖、save_message 原子去重 (INSERT OR IGNORE)、media_files 同事务写入。P2: iter_messages FloodWait 保底、--purge-after-export VACUUM、VACUUM<10MB 跳过。P3: --skip-discover/`--match-mode word
v3.92026-06-05🧹 数据保留策略。新增 --retention-days（默认 90 天自动清理）、--no-vacuum、--purge-after-export。新增 media_files 表追踪媒体文件。每次运行结束后自动清理过期消息、媒体文件和断点记录。新增 run_retention_cleanup() 统一入口
v3.82026-06-04🔧 backfill 发送者信息获取修复。新增 --fetch-sender 参数，通过 SenderCache（内存缓存） + 批量延迟策略安全获取发送者名称和用户名，避免 Flood Wait。新增 database.update_senders_batch() 延迟补充机制
v3.72026-06-03🔒 failover 安全加固。failover 必须用专属 code_acc{N}.txt，禁止共用验证码；不可恢复错误（2FA/密码/AuthKey）不触发 failover；连接失败后自动 disconnect
v3.62026-06-03P2: dry-run 模式。新增 --dry-run，不连接 TG 打印执行计划
v3.52026-06-03P3: 账号自动 failover。新增 --failover 参数，主账号 Flood Wait/凭证缺失时自动尝试后续账号
v3.42026-06-03P2: 数据库导出 CLI。新增 --export/--export-format/--since/--until/--chats 参数，支持 csv/json/markdown 三种格式导出
v3.32026-06-03P1: 搜索 Bot 结果 title 二次过滤。利用回溯阶段 get_entity 获取真实 title，不匹配的跳过 iter_messages
v3.22026-06-03P1: hybrid 断点续传。新增 channel_progress 表 + --no-resume 参数
v3.12026-06-03P1: backfill 新频道相关性过滤。hybrid stage2 跳过 title/username 与关键词不匹配的新频道
v3.02026-06-03P0: discover/backfill 关键词分离、6 行业 targets 分文件、三账号代理隔离、SOCKS5 认证
v2.02026-06-03三账号支持、TG Web 应急扫描、行业适配策略、羊毛频道预置、实战经验库
v1.02026-06-02Skill 化，四模式，71 频道，单账号
原型2026-05-20初始原型，66 外挂频道，backfill + monitor

TG 爬虫 Skill

基于 Telethon 的 TG 频道/群组消息采集与舆情监控工具。

触发条件

当用户提到以下任一意图时触发：

  • "扫描TG"/"搜一下 TG"/"TG 上有没有 XX 外挂"
  • "回溯 TG 消息"/"爬一下XX频道的消息"
  • "发现XX相关的TG频道"/"找一下XX的TG群"
  • "监控 TG 频道"
  • 更广义的舆情扫描任务中需要 TG 数据源时

⚠️ 核心规则：行业适配（必读）

TG 上不同行业的黑灰产分布在完全不同的频道生态中，搜索关键词必须根据目标行业调整。

行业TG 搜索关键词禁止用
🎮 游戏游戏名、外挂、辅助、破解优惠券、漏洞单
🥛 快消/零售优惠券、薅羊毛、漏洞、线报、Bug价、0元购外挂、破解
💰 金融套利、路子、代刷、水钱优惠券、外挂
📱 App破解版、Mod、去广告、解锁优惠券
💬 社交交友、引流、号商、脚本、代聊外挂
✈️ 航司里程、积分、代订、机票诈骗、退改签外挂
🚗 汽车车贷、二手车、违章代办、改表优惠券、外挂

两步法通用模式：

# 第1步：搜生态关键词 → 发现频道（用 discover 关键词）
# 第2步：在频道中搜品牌名 → 回溯消息（用 backfill 关键词）
python3 main.py --mode hybrid \
  --keywords "生态词1,生态词2" \
  --backfill-keywords "品牌名1,品牌名2" \
  --targets <行业profile> \
  --env ../config/.env

各行业两步法完整命令示例 → references/industry-playbook.md。

🛑 何时放弃 TG 渠道：目标行业是快消/传统零售/餐饮/医疗且 discover 阶段返回 0 频道 → 切到 web_search（微博/知乎/黑猫投诉）。

运行模式

模式命令说明
hybrid--mode hybrid --keywords "词"发现 + 回溯（推荐）
discover--mode discover --keywords "词"仅发现频道
backfill--mode backfill --limit 500对已有频道回溯
monitor--mode monitor7×24 实时监听
export--export results.csv导出数据（不连 TG）

参数速查

参数说明默认值
--modehybrid / discover / backfill / monitor—
--keywordsdiscover 搜索关键词，逗号分隔—
--backfill-keywordsbackfill 专属关键词，不传回退 --keywords—
--targets配置文件路径 或 行业 profile (gaming/retail/social/airline/auto/all)../config/targets.yaml
--backfill-limit单频道回溯消息条数500
--accountTG 账号 1/2/31
--failover失败后尝试后续 N 个备用账号0
--no-bots禁用搜索 Botfalse
--no-backfill-filter禁用新频道相关性过滤false
--no-resume禁用断点续传false
--fetch-sender🆕 获取发送者用户名/名称（缓存+批量延迟防Flood Wait）false
--sender-batch-size🆕 每批获取发送者数量15
--sender-batch-delay🆕 批次间延迟秒数3.0
--dry-run试运行：不连 TG，打印参数和频道数false
--retention-days🆕 数据保留天数，自动清理过期消息/媒体/断点记录90
--no-vacuum🆕 禁用清理后的 VACUUM 空间回收false
--purge-after-export🆕 导出完成后清空数据库和媒体文件（需确认）false
--skip-discover🆕 hybrid 模式下跳过频道发现，仅回溯已有频道false
--match-mode🆕 匹配模式: substring(子串)/word(词边界)/regexsubstring
--export导出文件路径（跳过采集）—
--export-formatcsv / json / markdowncsv
--since / --until导出时间范围 YYYY-MM-DD—
--chats导出限定频道 (逗号分隔 username)—
--db数据库路径../data/crawler.db
--sessionTelethon session 名tg_crawler
--password2FA 密码—
--log-levelDEBUG / INFO / WARNING / ERRORINFO

配置文件

.env（凭证 + 代理）

# 账号 1
TG1_API_ID=xxx
TG1_API_HASH=xxx
TG1_PHONE=+86xxx
TG1_PASSWORD=          # 2FA（可选）

# 账号 2
TG2_API_ID=xxx
TG2_API_HASH=xxx
TG2_PHONE=+86xxx

# 账号 3
TG3_API_ID=xxx
TG3_API_HASH=xxx
TG3_PHONE=+86xxx

# SOCKS5 代理（可选，每账号可独立）
# TG1_PROXY_HOST=45.xx.xx.1
# TG1_PROXY_PORT=1080
# TG2_PROXY_HOST=45.xx.xx.2
# TG2_PROXY_PORT=1080
  • 代理优先级： TG{account}_PROXY_HOST > PROXY_HOST（全局回退）
  • 账号 1 支持向后兼容 TG_API_ID / TG_API_HASH / TG_PHONE
  • Session 自动区分：tg_crawler.session / tg_crawler_acc2.session / tg_crawler_acc3.session
  • 🆕 发送者信息获取： FETCH_SENDER_INFO=true 启用 / CLI --fetch-sender 临时启用（v3.8 新增，通过 SenderCache + 批量延迟策略防 Flood Wait）

targets.yaml（频道列表）

放在 config/，格式参考 references/targets-format.md。按行业分文件：

  • targets_gaming.yaml — 76 个游戏外挂频道
  • targets_retail.yaml — 5 个羊毛频道
  • targets_common.yaml — 118 个自动发现的跨行业频道
  • targets_social.yaml / targets_airline.yaml / targets_auto.yaml — 空模板

验证码

# 命令行传入
python3 main.py --code "12345" --mode hybrid --keywords "游戏名"

# 文件读取（非交互环境）
python3 main.py --code-file /path/to/code.txt --mode hybrid --keywords "游戏名"

# 交互式输入（默认）
python3 main.py --mode hybrid --keywords "游戏名"

注意事项

  1. Flood Wait：TG API 严格限速，单次避免过大 --backfill-limit
  2. Session 文件：首次运行后生成，必须在 scripts/ 目录下运行 main.py
  3. 2FA：账号开启二次验证需传 --password
  4. web_fetch 应急：Flood Wait 阻塞时可用 web_fetch https://t.me/s/{channel}?q={关键词} 应急（限 ~20 条）
  5. 私密群组：需 invite_link，否则无法加入

数据保留策略（v3.9+）

机制默认值说明
消息保留90 天--retention-days N 调整，超期消息自动删除
媒体文件关联删除消息删除时关联的图片/视频同步清理
断点记录同步清理channel_progress 的超期记录一并清理
VACUUM自动执行清理后自动回收磁盘空间，--no-vacuum 禁用
彻底清空手动触发--export results.csv --purge-after-export 导出后清库

设计原则：

  • 舆情数据的时效性天然有限（超过 90 天的历史消息情报价值极低）
  • 自动清理避免 SQLite 数据库和 data/media/ 无限膨胀
  • 每次采集运行结束后执行清理，不影响采集性能

已知限制

限制应对
Flood Wait 全阻塞换账号/等冷却/--failover 自动切；短FloodWait(<60s)自动重试
web_fetch 只能 ~20 条应急用，不是 backfill 替代
频道发现仅限公开频道私密群需手动提供 invite_link
CPS 推广频道信息密度低采样分析，不必全量回溯
子串匹配误报用 keyword_rules.match_mode=word 减少误报
discover 重复搜索用 --skip-discover 跳过发现阶段
YAML 追加丢失注释v3.11 起用 dump 全量重写，注释不再保留（优先保证文件正确性）

相关文档

  • 行业两步法详细命令 + 羊毛频道预置列表 → references/industry-playbook.md
  • 代理池自建方案（VPS 对比 + Dante 脚本） → references/proxy-pool-setup.md
  • targets 格式说明 → references/targets-format.md
  • 完整架构设计 → references/tg-crawler-architecture.md
  • 爬虫源码 → scripts/