1. 项目概述一个基于Google Apps Script的Telegram机器人如果你在运营一个Telegram群组无论是技术交流群、兴趣社群还是工作小组肯定遇到过这些头疼事广告机器人无孔不入、成员争吵需要禁言、新人入群需要手动欢迎、或者想快速查询一些信息却要切出聊天窗口。手动管理费时费力而市面上的机器人要么功能不全要么需要自建服务器对新手极不友好。今天要聊的这个项目——XiaoMaoBot就完美地解决了这些痛点。它是一个完全基于Google Apps Script开发的Telegram机器人。GAS是什么你可以把它理解成Google为你免费提供的一个云端脚本运行环境能定时执行任务也能通过Webhook响应外部请求。这意味着你不需要购买VPS不需要配置Nginx或数据库甚至不需要懂太多后端知识就能拥有一个功能强大的群管机器人。我最初是在GitHub上发现这个项目的作者xiaomaoJT把它做得相当完善。从超级群管、敏感词过滤到对接ChatGPT查询、消息自动存储与推送功能覆盖了日常运营的绝大部分场景。最吸引我的是它的“零成本”和“模块化”。所有代码都跑在Google的服务器上你只需要一个Google账号而模块化的设计让你可以像搭积木一样按需启用或禁用功能不会让机器人变得臃肿。接下来我会带你彻底拆解这个机器人。从GAS环境搭建、BotFather注册、到核心功能模块的配置与原理我会分享每一步的实操细节以及我在部署和调试过程中踩过的坑和总结的技巧。无论你是想为自己的小群组找个“管理员”还是对Telegram Bot开发感兴趣这篇内容都能给你一份可以直接“抄作业”的指南。2. 核心架构与方案选型解析为什么选择Google Apps Script来构建Telegram Bot这背后是一套针对低成本、易部署和免运维需求的完整技术决策。我们来深入分析一下。2.1 为什么是Google Apps Script首先我们得明白Telegram Bot的两种主流通信方式长轮询和Webhook。长轮询你的服务器或脚本需要不断地、主动地向Telegram服务器发起请求询问“有没有新消息给我”这种方式实现简单但需要你的服务端7x24小时在线对资源有持续消耗。Webhook你告诉Telegram服务器一个公开的URL地址。当有消息发给你的Bot时Telegram会主动把这个消息“推送”到这个URL上。这种方式实时性高服务器只在有消息时才工作更节能。GAS天然适合Webhook模式。每个GAS项目在部署为“Web应用”后都会获得一个唯一的、HTTPS的终点URL。这个URL可以被设置为Bot的Webhook。当消息到来时Telegram将HTTP POST请求发送至该URL触发GAS中的doPost函数处理消息。选型优势分析零成本与免运维这是最大的吸引力。GAS免费配额对于个人或中小型群组的机器人来说完全够用。你无需关心服务器硬件、操作系统、运行环境或网络配置Google全包了。无缝集成Google生态机器人需要存储配置如敏感词列表、记录日志或保存消息吗GAS可以轻松调用Google Sheets电子表格和Google Drive。这意味着你的机器人的“数据库”就是一个在线表格可视化编辑无需额外搭建数据库。开发门槛低GAS使用JavaScript/TypeScript语法对于前端开发者或脚本爱好者非常友好。调试和日志查看可以直接在GAS的在线编辑器中进行。高可用性与安全性运行在Google的基础设施上具备良好的可用性。同时HTTPS和Google账户授权机制提供了一定的安全基础。当然也有其局限性执行时间限制GAS免费版单次脚本执行最长为6分钟。对于极复杂的消息处理链需要优化代码逻辑。每日配额限制有每日触发器执行次数、URL Fetch调用次数的限制。对于消息量巨大的超级群比如每分钟上百条可能需要监控配额使用情况。冷启动延迟长时间未被调用的GAS脚本再次被触发时会有几秒的“冷启动”时间可能导致响应稍有延迟。注意对于99%的普通社群来说GAS的免费配额绰绰有余。你需要警惕的是如果机器人被恶意刷消息可能会短时间内耗尽配额。因此在配置中做好频率限制和异常监控是关键。2.2 XiaoMaoBot的模块化设计思想打开项目的Modules目录你会发现功能被拆分得非常清晰command.js处理Bot命令如/start,/help,/ban。filter.js核心的广告与敏感词过滤逻辑。groupEvent.js处理用户加入、离开群组等事件。keyboard.js管理自定义回复键盘和消息内联按钮。messageHandler.js消息处理的总入口和路由。push.js实现私聊消息推送功能。query.js封装了对各种外部API如天气、翻译、ChatGPT的查询。utils.js存放工具函数如日志记录、配置读取。这种设计的好处是高内聚、低耦合。你想加强过滤功能就改filter.js想增加一个新的查询命令就在query.js里添加函数并在command.js里注册。模块之间通过清晰的接口调用而不是 spaghetti code面条式代码。这对于后续的功能扩展、问题排查以及社区贡献都极其友好。2.3 数据存储方案Google Sheets as DatabaseXiaoMaoBot使用Google Sheets作为核心的配置和存储中心这是一个非常巧妙的实践。通常我们会看到几个工作表Config存储机器人的全局配置如Bot Token、管理员ID、开关设置等。SensitiveWords存储需要过滤的敏感词或广告关键词列表支持动态增删。ChatHistory可选功能用于存储消息记录。UserStatus记录用户状态如是否被禁言、警告次数等。这样做的优势零配置无需安装MySQL、PostgreSQL。实时可视化管理管理员可以直接在网页表格里修改敏感词机器人通过GAS脚本读取几乎可以实时生效。易于备份与迁移整个“数据库”就是一个电子表格文件下载、上传、分享都非常方便。在代码中通过SpreadsheetApp.openById(‘你的表格ID’).getSheetByName(‘工作表名’)这样的API就能轻松读写数据。后续在实操环节我们会详细讲解如何创建和配置这个数据表。3. 从零开始部署环境准备与初始化理论说得再多不如动手做一遍。这部分是实操核心我会假设你从零开始带你完成整个部署过程。请严格按照步骤操作大部分问题都出在细节上。3.1 第一步创建你的Telegram Bot打开Telegram搜索并联系BotFather。发送命令/newbot。根据提示为你的Bot设置一个显示名称用户看到的和一个唯一用户名必须以bot结尾例如my_awesome_test_bot。创建成功后BotFather会给你一串至关重要的HTTP API Token格式类似1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。重要提示这个Token就是你的Bot的钥匙绝对不要泄露给任何人或上传到公开的Git仓库。任何人拿到这个Token都能完全控制你的Bot。我们后续会把它安全地存放到Google Sheets的配置表中。建议再对Bot进行一些基础设置/setdescription– 设置Bot的简介。/setabouttext– 设置Bot的关于信息。/setuserpic– 设置Bot的头像。/setcommands– 设置命令菜单。你可以发送一段列表定义用户输入/时看到的命令提示例如help - 显示帮助信息 ban - 封禁用户 warn - 警告用户最关键的一步将你的Bot拉入目标管理群并授予它管理员权限特别是“删除消息”、“封禁用户”、“邀请用户”这几项。没有管理员权限Bot无法执行群管操作。3.2 第二步配置Google Sheets数据表这是XiaoMaoBot的“大脑”所有配置都在这里。访问 sheets.new 快速创建一个新的Google电子表格。将其重命名为你容易识别的名字例如XiaoMaoBot_Config。按照项目要求创建对应的工作表。通常至少需要Config表用于存放核心配置。键值说明BOT_TOKEN你的Bot Token从BotFather获取ADMIN_ID你的Telegram用户ID用于接收通知和执行高级命令GROUP_ID你的群组ID机器人管理的群组ID可多个用逗号分隔WELCOME_MSG欢迎新朋友 {name}入群欢迎语{name}会被替换GOODBYE_MSG{name} 离开了我们。退群告别语AUTO_DELETE_WELCOME60欢迎消息在多少秒后自动删除0为不删除GPT_API_KEYsk-...可选OpenAI API Key用于ChatGPT功能GPT_API_URLhttps://api.openai.com/v1/chat/completions可选API地址可使用代理SENSITIVE_FILTER_ONTRUE是否开启敏感词过滤AUTO_REPLY_ONTRUE是否开启关键词自动回复SensitiveWords表用于存放过滤词库。类型关键词动作参数广告加微信delete敏感政治词汇ban刷屏111111warn3(警告3次后禁言)正则.*赌.*博.*delete如何获取你的Telegram用户ID和群组ID用户ID在Telegram中向userinfobot这个机器人发送任意消息它会回复你的ID。群组ID将你的Bot拉入群组后在群组中发送一条消息。然后在浏览器中访问这个URL将YOUR_BOT_TOKEN替换https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates在返回的JSON数据中找到message对象下的chat-id那个负数如-1001234567890就是你的超级群组ID。普通群组的ID是负数频道的ID以-100开头。记录下这个Google Sheets的文件ID。打开表格浏览器地址栏的URL格式为https://docs.google.com/spreadsheets/d/【这里就是文件ID】/edit。复制这个ID稍后在GAS脚本中会用到。3.3 第三步创建并部署Google Apps Script项目访问 script.new 创建一个新的GAS项目。在项目设置中齿轮图标将项目名称改为XiaoMaoBot并确保“默认时区”符合你的所在地。将XiaoMaoBot项目Modules目录下的所有.js文件代码逐个复制到你的GAS项目中创建对应的脚本文件。同时将主入口文件通常是main.js或Code.js的代码复制到默认的代码.gs文件中。实操心得不要一次性复制全部。建议先复制utils.js和main.js确保基础运行环境。GAS的编辑器对大型单文件支持不如现代IDE模块化拆分是明智之举。在utils.js或类似负责初始化的文件中找到读取配置的代码段。你需要修改其中的SPREADSHEET_ID变量将其值替换为你刚才记录的Google Sheets文件ID。// 示例代码片段 const SPREADSHEET_ID 你的Google Sheets文件ID; const CONFIG_SHEET_NAME Config; // ... 其他配置授权与测试首次运行需要授权。点击编辑器上方的“运行”按钮三角图标选择初始化或配置读取相关的函数例如setup或testConfig。GAS会弹出窗口要求你授权它访问你的Google Sheets和外部网络用于调用Telegram API。请仔细阅读权限说明主要是读写你创建的表格和发送网络请求然后同意。编写一个简单的测试函数并运行确保能正确从Sheets中读取到BOT_TOKEN。function testBotToken() { const config loadConfig(); // 假设这是你读取配置的函数 console.log(Bot Token (前5位):, config.BOT_TOKEN.substring(0, 5)); // 千万不要在日志中打印完整的Token }在“执行日志”中查看输出确认配置读取成功。3.4 第四步设置Webhook这是连接你的Bot和GAS脚本的最后一步。在GAS编辑器中点击“部署” - “新建部署”。选择类型为“Web应用”。“执行身份”选择“我”你的Google账户。“谁有权访问”选择“任何人”。这是关键因为Telegram的服务器需要能访问这个URL来推送消息。点击“部署”。系统会生成一个部署ID和一个Web应用URL。复制这个URL。设置Webhook。你需要通过浏览器或命令行工具访问一个特定的Telegram API链接来告诉Telegram你的Webhook地址。将下面的链接中的YOUR_BOT_TOKEN和YOUR_WEB_APP_URL替换后在浏览器中访问https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook?urlYOUR_WEB_APP_URL例如https://api.telegram.org/bot123456:ABCdef/setWebhook?urlhttps://script.google.com/macros/s/AKfycby.../exec如果设置成功浏览器会返回一个JSON响应其中ok: true。你可以通过以下链接验证Webhook信息https://api.telegram.org/botYOUR_BOT_TOKEN/getWebhookInfo至此你的机器人骨架已经搭建完成。回到Telegram在你的群里发送一条消息或者给Bot发送/start命令看看它是否能够响应。如果一切正常恭喜你最复杂的部分已经完成。4. 核心功能模块深度配置与实战基础框架跑通后我们来深入几个最常用、也最容易出问题的功能模块看看如何配置和优化。4.1 敏感词过滤系统的精细化配置敏感词过滤是群管机器人的核心防线。XiaoMaoBot的实现通常位于filter.js模块。工作原理简述监听机器人监听群内每一条新消息文本、图片标题、文档名称等。匹配将消息内容与SensitiveWords表格中的关键词列表进行比对。匹配方式支持精确匹配、模糊匹配包含和正则表达式匹配功能最强大。执行动作根据表格中配置的“动作”字段执行相应操作delete: 仅删除消息。warn: 删除消息并对发送者发出警告。警告次数可累积达到阈值如3次后自动触发mute或ban。mute: 禁言用户一段时间如10分钟。ban: 将用户永久踢出群组并封禁。配置实战与技巧正则表达式的威力对于变体广告正则表达式是利器。例如过滤所有“加V信”的变体类型关键词动作正则加[\\s\\S]*[VvWw微][\\s\\S]*信delete这条规则可以匹配“加 V 信”、“加微❤️信”、“加WX”等多种变体。注意GAS中使用的JavaScript正则引擎。过于复杂的正则或对超长消息进行匹配可能会触及GAS的执行时间限制6分钟。建议先测试再上线。分级处理策略不要对所有违规行为一刀切。建议分级一级广告链接直接delete。二级轻度刷屏、无关话题warn并记录次数。三级人身攻击、严重违规直接ban。 在SensitiveWords表中可以通过“类型”和“参数”列来实现复杂策略。误判处理与白名单任何过滤系统都有误判可能。一个健壮的系统应该提供白名单机制。你可以在代码中维护一个管理员ID或可信用户ID的数组或者在Sheets中新增一个WhiteList表。在filter.js的匹配逻辑前先判断发送者ID是否在白名单内如果是则跳过过滤。// 伪代码示例 function shouldFilter(userId) { const whiteList loadWhiteList(); // 从Sheets或配置加载白名单 return !whiteList.includes(userId); }4.2 利用ChatGPT接口实现智能问答XiaoMaoBot集成了OpenAI的ChatGPT API让机器人能进行智能对话。配置关键在于Config表中的GPT_API_KEY和GPT_API_URL。配置步骤获取OpenAI API Key访问 OpenAI平台 创建新的API Key。将Key填入Config表的GPT_API_KEY字段。可选如果你需要解决网络访问问题可以使用一个可靠的反向代理地址替换默认的GPT_API_URL。社区有一些公开的代理服务但稳定性和安全性需自行甄别。切勿使用来路不明的代理。在query.js或相关模块中找到调用API的函数。通常需要配置以下参数const payload { model: gpt-3.5-turbo, // 或 gpt-4 messages: [{ role: user, content: userMessage }], temperature: 0.7, // 创造性0-2之间 max_tokens: 1500 // 回复的最大长度 };成本控制与优化设置使用权限在代码中限定只有管理员、或特定群组、或通过命令如/ask才能触发GPT查询避免被滥用导致API费用激增。上下文管理简单的实现是“一问一答”没有上下文记忆。更高级的实现可以将对话ID和最近几条消息缓存在Sheets或CacheService中实现有限轮次的上下文对话但这会消耗更多token。设置消息长度限制在代码中检查userMessage的长度如果超过一定字符数如500字则拒绝处理或进行摘要后再提问。监控用量定期查看OpenAI平台上的用量统计做到心中有数。4.3 消息推送与存储打造私人助理这个功能非常实用它允许你将指定群组的消息或符合特定条件的消息自动转发到你的私人聊天窗口。实现原理消息捕捉在messageHandler.js中对所有流经机器人的消息进行判断。条件过滤判断消息是否来自需要监听的群组GROUP_ID并且可能根据关键词、发送者等进行二次过滤。私人推送调用Telegram Bot API的sendMessage方法将消息内容包括发送者信息、时间、原始消息链接发送到管理员的私人IDADMIN_ID。配置与应用场景关键信息不漏在你无法时刻关注的技术支持群或项目群设置关键词如“你”、“紧急”、“bug”让机器人你或推送消息给你。跨群组管理如果你管理多个群可以在每个群都部署同一个Bot通过配置多个GROUP_ID然后所有群的动态都汇总推送到你这里。审计与备份结合messageHandler.js中的存储功能可以将所有消息或特定消息自动记录到Google Sheets的ChatHistory表中方便事后追溯。字段可以包括时间戳、消息ID、群组ID、用户ID、用户名、消息内容。隐私提醒此功能涉及数据收集请在群规中明确告知成员并严格遵守相关法律法规。仅用于必要的管理和运营目的。5. 高级调试、问题排查与性能优化即使按照教程一步步来也难免会遇到问题。这里我总结了一些常见的坑和解决办法。5.1 常见问题速查表问题现象可能原因排查步骤与解决方案Bot完全无响应1. Webhook未设置或设置错误。2. GAS脚本未部署或部署失败。3. GAS脚本执行出错。1. 访问getWebhookInfo链接确认url是否正确。2. 在GAS编辑器重新部署确保“谁有权访问”为“任何人”。3. 在GAS编辑器的“执行日志”中查看最新错误信息。Bot能收到命令但无回复1.BOT_TOKEN配置错误。2. GAS脚本中发送消息的代码逻辑有误。3. Google Sheets配置表读取失败。1. 检查Config表中的Token是否完整无误前后无空格。2. 在doPost函数开始处添加日志打印接收到的原始数据确认流程走到发送消息前。3. 编写一个独立测试函数测试从Sheets读取数据是否正常。敏感词过滤不生效1.SENSITIVE_FILTER_ON开关为FALSE。2. 敏感词表SensitiveWords格式错误或为空。3. 匹配逻辑有bug或关键词有特殊字符。1. 检查Config表开关。2. 检查SensitiveWords表头是否正确数据是否从第2行开始。3. 在filter.js中添加调试日志打印待匹配消息和词库检查匹配过程。GAS脚本报“超时”错误1. 单次处理逻辑太复杂超过6分钟限制。2. 网络请求如调用ChatGPT API耗时过长。1. 优化代码逻辑将非核心操作异步化或移除。2. 为外部API调用设置合理的超时时间如30秒并使用Utilities.sleep()在重试前等待。机器人响应速度慢1. GAS冷启动延迟。2. 读取Google Sheets数据次数过多。1. 这是GAS特性无法根除。可考虑设置一个每分钟触发一次的“空跑”触发器保持脚本活跃。2. 使用GAS的CacheService将频繁读取的配置如敏感词缓存起来例如缓存5分钟而不是每次都读Sheets。无法删除消息或禁言用户1. Bot在群组中不是管理员。2. Bot的管理员权限未包含“删除消息”和“封禁用户”。3. 尝试操作其他管理员或创建者的消息。1. 确认Bot已被设为群管理员。2. 在群组设置中编辑Bot的管理员权限勾选所有必要的权限。3. Telegram限制Bot无法删除群主或更高权限管理员的消息。5.2 性能优化与最佳实践当你的群组越来越活跃或者功能越加越多时以下几点优化能让你的机器人更稳定善用缓存CacheService是GAS提供的键值对缓存。将SensitiveWords这类不常变化但频繁读取的数据放入缓存能极大减少对Sheets的读写次数提升响应速度并节省配额。function getCachedSensitiveWords() { const cache CacheService.getScriptCache(); let words cache.get(sensitive_words); if (!words) { words loadFromSheet(); // 从Sheets读取 cache.put(sensitive_words, JSON.stringify(words), 300); // 缓存5分钟 } else { words JSON.parse(words); } return words; }日志记录策略不要滥用console.log。GAS的日志输出有配额限制。建议将重要的错误信息、操作记录如封禁用户写入一个专门的Google Sheets“Log”工作表而仅将关键流程节点信息输出到控制台用于调试。错误处理与重试网络请求如调用Telegram API或外部查询API可能失败。务必使用try...catch包裹并实现简单的重试机制。function sendMessageWithRetry(chatId, text, retries 3) { for (let i 0; i retries; i) { try { // 调用发送消息API return true; // 成功则返回 } catch (e) { console.error(发送失败 (尝试 ${i1}/${retries}):, e); if (i retries - 1) Utilities.sleep(1000 * (i 1)); // 等待时间递增 } } return false; // 全部重试失败 }配额监控定期在GAS编辑器点击“执行”-“配额”查看每日URL Fetch调用次数、触发器运行时间等是否接近上限。如果用量很大需要考虑优化代码或升级到Google Workspace付费计划。代码版本管理GAS虽然在线编辑方便但版本管理较弱。建议将重要的脚本版本通过“文件”-“管理版本”创建版本快照。在部署重大更新前先创建一个新版本进行测试稳定后再切换。部署和运营这样一个机器人就像养一个数字员工。初期搭建需要耐心一旦稳定运行它能为你节省大量重复性管理时间。最重要的是理解其工作原理这样当出现问题时你才能快速定位并解决。希望这份超详细的指南能帮你顺利拥有自己的得力Telegram群组助手。