简介电报群关键词监听机器人源码面向社群运营、营销获客与消息监控场景解决人工盯群效率低、无法第一时间捕获目标关键词的问题。基于普通账号即可运行监听账号混在群内不易被察觉适合需要多群、多频道同时监控并实时通知运营者的团队。资源共46个文件压缩包仅110KB以36个PHP代码文件为主体涵盖机器人核心逻辑、事件监听、客户端封装、控制器等模块同时包含JSON关键词配置、容器化部署配置、Shell启停脚本和一份详细的docx使用教程便于快速部署与二次开发。源码目录结构清晰附有依赖管理、环境变量示例及迁移文件方便按需扩展关键词触发规则、接入更多群组。目前已有773人学习下载适合有一定PHP基础、希望自建营销监控工具的开发者。1. 普号监听TG群为什么不用Bot API而用源码包里常见的Telethon方案一个挂着“关键词监听机器人 TG电报群消息 监听机器人源码(普号) 关键词监控支持人工实时监听”的压缩包近年在技术资源群里转得很勤。多数人拿到手以为解压、填个Token就能跑结果卡在第一步它压根不用Bot Token而是要求Telegram普通账号登录。这个“普号”设计不是随手写的Bot在群消息场景里有一堆先天限制而用Telethon这类MTProto客户端库、以普通账号身份进群监听才是这类源码包的真正技术底座。它解决的是“把群里特定关键词消息实时筛出来交给真人”这件事适合做群内业务线索监控、同行情报跟踪或舆情值班的人也适合想学Telethon事件流怎么用的开发者。2. 监听机器人的原理与选型Bot API的四个边界普号路线的取舍2.1 Bot API监听群消息的四个卡点第一Bot进入群的动作本身就会暴露身份。群成员列表里会出现一个带“bot”标记的账号管理员后台能看到机器人权限。我见过不少技术群专门有“清理机器人”的定时任务Bot身份进了这种群没过几天就被移出去了。第二Bot看不到它入场之前的历史消息。关键词监听往往刚入场就想立刻有产出但Bot登录的那一刻是从零开始的群里旧消息对它是不可见的除非依赖群归档或自建历史库这不是一个小工具能实现的。第三Bot读消息依赖群管理方的“允许机器人”设置。Telegram群对机器人消息读取有独立开关部分群限制后Bot即使被拉进去也只能收到一部分事件且不同客户端表现不一致代码层面防不胜防。第四Bot API的更新靠长轮询推进多群场景下轮询间隔和offset管理写不好会出现漏消息或重复拉取实时性上限摆在那。普号走MTProto后事件流由服务端主动推送回调触发是毫秒级的这个差异正是不少源码包选择普号的原因。2.2 普号监听走什么协议MTProto与Telethon普通账号登录走的是Telegram私有协议MTProtoTelethon是Python生态里对这个协议封装最完整的一个客户端库。为什么源码包普遍会选中它因为Telethon的事件模型就是为“监听”设计的注册一个client.on(events.NewMessage(...))就能实时收到新消息不需要自己维护offset也不用来回处理Webhook签名。这一类普号客户端库常见的有Telethon、Pyrogram、GramJS其中Telethon社区资料最多最容易拿来做群消息监控。普号的监听范围有一条明确的边界只有账号已经加入的群才会收到新消息事件。Telethon拿不到未加入群的内容这与Bot可以靠公开链接直接加入有差别。普号加入目标群必须账号手动确认或通过邀请机制完成。这个边界决定了源码包不是“全网监控”而是“已加入群监控”动手前先确认目标群是否接受普通账号入驻。登录形态上普号需要三样东西手机号、API ID、API Hash。API ID和API Hash到Telegram应用管理页申请即可关键是这套接入凭证与session文件绑定。第一次登录会走验证码Telethon把登录态序列化到本地session文件之后每次启动直接加载session不再需要输入验证码。这个机制是普号监听能长期跑的基础也是很多部署翻车的地方换了session路径、换机器不迁移session都会重新触发登录。2.3 选型对照表与落地方向对比项Bot API 路线普号 Telethon 路线登录凭据BotToken手机号 api_id api_hashsession复用读取已加入群消息需要群配置开放权限账号可见群的新消息直接可读历史消息回溯基本不可见有限窗口回溯依赖客户端保留断线恢复依赖offset重置事件流恢复配合session持续在线身份暴露成员列表带bot标记表现为普通账号怎么判断普号路线适不适合你两个前提一是有可用的低活跃Telegram账号二是目标群允许普通账号加入。两者缺一就退回Bot方案或干脆放弃。源码包里写“(普号)”是对方案的诚实标注它默认使用者有自己的账号、能自己加入群。如果误以为它是输入任意群链接就能监控的通用工具大概率会失望。3. 用Telethon搭最小监听链路从登录到收消息的完整命令3.1 注册API ID与申请接入凭证的步骤到 my.telegram.org 用目标账号登录进入 API development tools填一个应用标题和短名称平台会返回 api_id 和 api_hash 两串值。这两串只是接入凭证不是Bot Token也和在BotFather里创建的那个“机器人”没有关系。如果之前创建过页面会直接展示已有凭证可以复用。常见误区是在BotFather里建机器人、抄Token然后在Telethon里用Token登录那是另一条客户端路径不属于普号监听。pip install telethon装完后建议确认cryptg是否被一并拉进来这是Telethon的可选加速扩展很多登录卡顿和事件解码异常在装了它之后不再出现。API凭证我习惯放到环境变量里而不是写死在脚本里源码包经过多手转发写死在文件里的凭证等于变相公开账号风险自己背。3.2 最小监听代码处理登录、验证码、两步验证下面这段是Telethon登录的最小骨架先只验证登录态再挂监听。第一次运行会交互输入手机号、验证码、两步验证密码之后靠session复用就不需要了。from telethon import TelegramClient, events import os, asyncio API_ID int(os.getenv(TG_API_ID)) API_HASH os.getenv(TG_API_HASH) SESSION monitor # session文件名登录态保存在 monitor.session client TelegramClient(SESSION, API_ID, API_HASH) async def start_client(): await client.start( phonelambda: input(手机号(带国家码): ), code_callbacklambda: input(验证码: ), passwordlambda: input(两步验证密码(没有则回车): ) ) me await client.get_me() print(已登录:, me.username or me.id) async def main(): await start_client() await client.run_until_disconnected() if __name__ __main__: asyncio.run(main())phone、code_callback、password三个回调对应Telegram登录的三道关卡两步验证没开启时password回调直接回车即可。get_me()用来确认登录成功返回当前账号实体。run_until_disconnected()是阻塞调用连接断开时会抛异常退出生产部署要在外层加重连循环。上面这个脚本只登录不监听。事件监听还要加一个handlerclient.on(events.NewMessage(chats[-100123456789])) async def on_msg(event): text event.raw_text or if 关键词 in text: print(f命中: chat{event.chat_id} user{event.sender_id} msg{event.message.id}) print(text[:200])chats参数可以传群ID、群username或它们的列表raw_text拿到的是去掉格式的纯文本sender_id是发送人ID群里匿名发送时可能是None代码里要做好空值判断event.message.id是群内消息序号是后续去重和回溯定位的唯一键。这里的关键词判断是直接用in只适合规则少的场景规则一多就要换成预编译正则。3.3 监听前先解决群来源Chat ID和用户名两种拿法监听脚本写好后最大概率卡在chats参数不知道填什么。先用一个小脚本列出当前账号所有会话把目标群的实体ID拿到手from telethon import TelegramClient import os, asyncio client TelegramClient(debug_session, int(os.getenv(TG_API_ID)), os.getenv(TG_API_HASH)) async def list_chats(): await client.start() async for dialog in client.iter_dialogs(): print(fid{dialog.id} | name{dialog.name} | entity{dialog.entity}) if __name__ __main__: asyncio.run(list_chats())iter_dialogs()会拉取账号可见的全部会话包括私聊、群和频道。群ID通常是负数频道ID也是负数私聊是正数这个符号差异在Telethon实体体系里有明确区分。只要群不重建ID基本稳定公开username反而可能被改所以我更推荐把打印出来的群ID固化到监听配置里。会话数量多时iter_dialogs()会慢可以先跑起来等几秒也可以按名称过滤提前定位。4. 关键词监控与人工实时监听规则引擎、命中触发与可靠性4.1 关键词规则怎么设计包含、正则、排除词与误报抑制关键词监听的返工重点在规则。第一批使用者普遍把“关键词”理解成字符串列表代码里if keyword in text草草了事上线第一天就被误报淹没。带人工实时监听的场景命中后是真人逐条去看规则设计要本着“宁错过、不误杀”的底线。我常用的三层匹配结构字符预过滤 → 包含判断 → 正则精匹配。第一层用字符集合快速跳过大部分无关消息第二层做低成本粗筛第三层用正则控制词的边界和上下文。高频群一天几千条消息字符预过滤能挡掉八成真正的正则只在小范围文本上跑。PRE_FILTER {价格, 货源, 放量, 名额, 出单} PATTERNS [ r价格\s*[:]\s*(\d), r(货源|货量)\s*[:]\s*(\S), r放量\s*(发售|开盘|启动), ] import re compiled [re.compile(p) for p in PATTERNS] def match_keywords(text): if not any(ch in text for ch in PRE_FILTER): return [] hits [] for pat in compiled: m pat.search(text) if m: hits.append((pat.pattern, m.group(0))) return hitsPRE_FILTER是字符级预过滤集合集合里的子串并不代表最终命中只是让消息先过一遍快速筛compiled在进程启动时一次性编译完成避免每条消息都触发编译开销。排除词我单独维护一个列表命中后先查排除词命中则直接丢弃避免“价格”这种词在闲聊语境里反复触发。正则里的分组捕获不只是为了好看还能把后续人工确认要看的核心片段直接提取出来。4.2 命中后的三条落地路径控制台输出、转发到人的聊天、写入审计文件人工实时监听要回答一个问题命中之后人在哪里看我通常三条路径同时开控制台输出用于本地调试转发到Telegram“已保存消息”作为手机端的实时推送入口写入JSONL文件留底。send_message(me, ...)是发给自己的私聊也就是Telegram里的“已保存消息”手机端会实时弹出通知这是最轻量的人工监听入口。async def on_hit(event, text, hits): chat_name event.chat.title or str(event.chat_id) payload f[关键词监听] 群: {chat_name} | 命中: {hits} | 原文: {text[:300]} # 路径1: 控制台 print(payload) # 路径2: 推送到自己的已保存消息 await client.send_message(me, payload) # 路径3: 追加写入审计文件按天分片 with open(fhits_{time.strftime(%Y%m%d)}.jsonl, a, encodingutf-8) as f: f.write(json.dumps({ chat_id: event.chat_id, msg_id: event.message.id, text: text[:300], hits: hits }, ensure_asciiFalse) \n)send_message(me, ...)不需要查任何ID固定的“已保存消息”入口写起来最省事。审计文件里必须带chat_id和msg_id这是事后回群里定位原始消息的两把钥匙只存文本的话回溯成本极高。提示一句不要做全量消息落库只落命中消息存储和隐私压力都会小很多。4.3 延迟与重试FloodWait、断线重连与消息去重群监控进程不是跑一次就结束长时间运行一定会遇到限流、断线、重复投递三类问题。Telegram对账号级请求有速率限制超限时会抛FloodWaitError异常里带着需要等待的秒数。Telethon有个flood_sleep_threshold参数设成某个秒数后等待耗时低于该值会自动休眠但设太大会让整个进程睡十几分钟实时性全丢。client TelegramClient(SESSION, API_ID, API_HASH, flood_sleep_threshold60)我建议把发送动作做成独立的asyncio队列接收和发送解耦。接收事件只做判断和入队发送协程按固定速率从队列消费。这样即使某一瞬间命中聚簇也不会因为连续发送触发限流。队列模型加上了FloodWait出现的概率能降一半。消息去重靠event.message.id。Telethon在断线重连后可能把断档期间积压的消息重新投递一次没有去重就会对同一条消息连续报警。用collections.deque维护最近一批msg_id集合命中前先查重重复直接丢弃。5. 部署排坑普号监听的5个常见问题与排查办法5.1 登录时死活收不到验证码现象首次启动Telethon输入手机号后没有验证码短信等十几分钟也无动静。原因最常见是手机号国家码写错其次是Telegram账号判定为新登录设备验证码改发到已登录App内的登录通知而不是短信。解决先在手机端Telegram检查“设置 → 隐私和安全 → 登录”确认“新登录设备”的通知推送是打开状态再核对手机号带完整国家码比如86开头最后留意Telethon交互提示里有没有“Sent a code to your other device”这类文案有就切到App内取码短信是没有的。5.2 一启动就报FloodWaitError被限流的真实原因现象进程刚跑起来日志里频繁出现FloodWaitError短则几十秒长则几百秒毫无规律。原因Telegram对账号级请求有整体速率限制普号被风控的概率比Bot更高。刚登录完就密集调用get_dialogs、send_message、轮询会话信息最容易集中触发。解决先减少请求量。监听代码只保留目标群的chats参数不要全量遍历所有会话发送动作并入队列限速两个请求之间保持至少1秒间隔如果账号已经被限解限的唯一办法是停止该账号一切自动化操作等自然恢复。误信“把超时参数调大就能绕过”的最后都会等账号解封。5.3 群消息明明有却不触发会话登录态与Chat ID漂移现象脚本运行正常登录也成功但目标群里来了新消息回调没有任何反应。原因三种情况最常见。一是chats参数填的是旧ID群重建后ID变化二是session文件在别的环境启动过登录态还在但事件路由失效三是账号被群管理员移除Telethon的session缓存还保留着该群的实体信息看起来像能监听。解决先跑一次会话列表脚本确认目标群仍在账号可见范围内再用client.get_entity()重新解析目标群实体把返回值验证后固化到配置里最后确认账号还在群内。事件不触发时不要急着改代码回到会话列表那一步查这是玄学最少的一步。5.4 关键词一多CPU就飙正则编译与提前过滤现象关键词加到几十条后CPU占用随消息量线性上涨风扇开始明显噪音。原因每条消息都走几十次正则匹配并且每次匹配都在重新编译pattern。Python的正则编译开销不小高频群场景下累积效应非常明显。解决把pattern在进程启动时一次性编译好用PRE_FILTER字符集合做提前过滤字符没命中直接跳过正则低频词用in判断高频词才进正则。消息文本超长时直接截断或跳过避免极端文本拖慢整个handler。调整后同样的消息量CPU占用能降到原来的十分之一。5.5 服务器跑了一天突然掉线连接不健康与重连参数现象进程稳定跑了一天第二天静默掉线不打印任何错误事件也不触发。原因Telethon维持的长连接被服务端断开session文件还在但没有异常抛出也没有新事件。常见于用nohup启动后 stdout 没有落盘、错误全丢的场景。解决把main()包进带重连的循环捕获连接断开异常先sleep再重新进入事件循环同时用systemd或supervisor托管进程退出自动拉起。session文件在启动时校验存在则直接加载不存在才走登录流程启动耗时控制在毫秒级。我还会给进程加定时重启避免长连接无限老化。6. 让监听机器人真正能用的三个进阶技巧6.1 用消息ID做幂等去重断线重连不重复报警命中处理前先把event.message.id放进一个带上限的集合重复消息直接丢弃。集合用deque加set组合只保留最近2000个ID内存占用可忽略。这个技巧在重连后最明显Telethon重连会把断档期间的积压消息重新投递没有去重就会对同一条消息连续报警三次。6.2 把“关键词”升级成“规则组”排除词屏蔽清单时段开关单一关键词列表很难长期使用同一个词在不同群里的含义完全不同。我会把规则按群拆成独立配置组每个群单独配关键词、排除词、生效时段。比如监控交易群时“价格”只在前缀带“收/出”时触发监控行业群时“放量”需要和当日上下文一起判断。这些规则全部用JSON配置运行时不热加载改完配置重启进程即可结构清晰出问题也好回退。6.3 监控结果落到结构化文件后再做二次消费记录命中的JSONL不只是审计它还是后续调整规则的原料。按天分片后用pandas或SQLite就能统计出“这个群这个关键词每天出现多少条、集中在几点”。没有监控数据的工具是没法迭代的。我自己最常犯的错是部署完就扔着不管误报比例一直没降后来养成的习惯是每两周回看一次JSONL把高频误报词加进排除词集合把漏报场景补进正则关键词监控才真正开始贴近业务判断。还有一个细节session文件定期备份。Telegram账号切换设备时可能触发验证流程一旦session失效重新登录要再走一遍验证码提前备份session可以让恢复成本降到最低。这是后悔药平时顺手做一次关键时刻省一晚上。用普号做关键词监听部署链路并不长真正花时间的是把关键词规则和告警口径调到不吵不漏。希望帮到你。本文还有配套的精品资源点击获取