1. 项目概述为OpenClaw的Telegram频道添加一键审批按钮如果你正在使用OpenClaw并且像我一样把Telegram作为主要的交互和通知渠道那你肯定对下面这个场景不陌生AI助手在执行某个需要授权的命令比如exec时会弹出一条审批请求。在Discord里这通常是个带按钮的漂亮消息框点一下“允许”或“拒绝”就完事了。但在Telegram里你得到的往往是一段冷冰冰的文本里面包含一个长得要命的UUID你得手动复制它然后输入类似/approve 123e4567-e89b-12d3-a456-426614174000 allow-once这样的命令。这不仅打断了工作流体验上也差了一大截。这个名为openclaw-telegram-approval-buttons的插件就是为了解决这个痛点而生的。它的核心目标极其明确将OpenClaw在Telegram以及Slack中的文本审批请求自动转换成带有一键操作按钮的富文本消息。你不用再打字不用再复制粘贴UUID只需要轻轻一点“允许一次”、“始终允许”或“拒绝”审批就完成了。这听起来是个小改进但对于每天要处理大量自动化任务和AI交互的开发者或运维人员来说体验提升是巨大的。这个插件完美诠释了“好的工具应该隐形”的理念。安装配置好后它会在后台默默工作拦截原本的文本审批消息将其“升级”为带按钮的交互式消息。整个流程对用户完全透明你只会感觉到审批变得无比顺畅。接下来我会详细拆解这个插件的设计思路、配置要点、内部工作原理并分享我在部署和使用过程中积累的一些实战经验和避坑技巧。2. 核心设计思路与架构解析2.1 为什么需要独立的审批按钮插件首先我们需要理解OpenClaw的审批机制。OpenClaw的网关Gateway在处理像exec执行命令这类高风险工具时如果配置为需要审批ask模式它会生成一个审批请求。这个请求本质上是一条消息包含了操作详情和一个唯一的UUID。网关需要将这条消息发送到某个配置好的频道如Telegram并等待来自该频道的授权回复。Discord频道原生支持更丰富的消息组件如按钮因此OpenClaw可以很容易地在Discord中构建交互式审批界面。然而Telegram和Slack的OpenClaw频道驱动最初可能更侧重于基础的文本消息收发没有内置对这类交互式审批UI的支持。这就导致了用户只能收到原始文本。这个插件的设计哲学不是去修改OpenClaw核心或频道驱动而是采用“装饰器”或“拦截器”模式。它作为一个插件挂载到OpenClaw的消息发送流程中。当网关试图向Telegram发送一条审批请求消息时插件会先拦截这条消息解析其内容识别出这是一个审批请求然后利用Telegram Bot API的能力重新构造并发送一条带内联键盘Inline Keyboard的消息。同时它会取消原文本消息的发送从而实现“偷梁换柱”。2.2 无状态与有状态设计的权衡一个关键的设计决策是如何跟踪“待处理”的审批。当用户点击按钮时系统必须知道这个点击对应的是哪个具体的审批请求即哪个UUID。这里有两种主流方案Webhook回调有状态复杂为插件单独设置一个HTTP服务端点Webhook当用户点击按钮时Telegram会将回调数据发送到这个端点。插件再根据回调数据中的信息向OpenClaw网关模拟发送审批命令。合成消息无状态巧妙将审批的UUID和操作类型如allow-once编码在按钮的回调数据callback_data中。当用户点击按钮时Telegram会向绑定的Bot发送一个回调查询Callback Query。如果Bot正确处理了这个查询并回答OpenClaw的Telegram驱动能够将这个回调查询自动转换并注入为一条模拟的文本消息内容就是/approve uuid action。这个插件采用了第二种方案这也是它最精妙的地方。它完全不需要自己搭建一个Webhook服务器。它只需要确保当用户点击按钮时Bot能正确响应Telegram的回调查询比如发送一个“操作成功”的提示。剩下的工作由OpenClaw核心的Telegram集成层完成它会捕捉到这个回调解析出callback_data并将其当作一条用户发送的文本命令传递给网关。这意味着插件本身几乎是无状态的架构大大简化部署成本极低。2.3 插件架构模块拆解从项目结构看插件的代码组织非常清晰遵循了单一职责原则index.ts插件入口负责生命周期管理和流程编排。它订阅OpenClaw的message_sending事件这是拦截审批消息的钩子。lib/approval-parser.ts核心解析器。它的任务是识别一条消息是否为OpenClaw的审批请求。它需要从消息文本中精准地提取出UUID、命令详情、请求用户等关键信息。这通常需要通过正则表达式匹配OpenClaw特定的文本格式。lib/telegram-api.ts封装了与Telegram Bot API的交互包括发送带内联键盘的消息、响应回调查询、编辑消息用于点击按钮后更新状态等。lib/approval-store.ts一个轻量级的内存存储用于跟踪已发送但尚未处理的按钮消息。为什么需要这个主要是为了处理“过期”逻辑。当用户长时间不点击按钮插件需要能够清理这些“僵尸”审批并将对应的消息标记为“已过期”。这个存储记录了消息ID、关联的Chat ID和过期时间。lib/message-formatter.ts负责将解析出的审批信息格式化成美观、信息丰富的Telegram消息文本支持Markdown或HTML并构建附带的按钮布局。lib/diagnostics.ts处理配置解析和健康检查。它实现了/approvalstatus命令让用户能快速验证插件配置和运行状态。types.ts集中定义整个插件用到的TypeScript接口保证类型安全。这种模块化设计使得代码易于理解、测试和维护。例如如果想支持另一个平台比如钉钉理论上只需要实现一个新的*-api.ts和*-formatter.ts并在入口处进行路由即可。3. 从零开始的完整配置与部署指南理论讲完了我们动手把它跑起来。假设你已经有一个正在运行的OpenClaw实例并且已经配置好了Telegram频道。3.1 环境与前提检查在开始之前请确保你的环境满足以下条件这能避免很多后续问题OpenClaw版本确保你的OpenClaw版本至少是2026.2.9或更高。插件可能会依赖特定版本引入的API或特性。检查命令openclaw --version。Node.js版本插件要求Node.js20。因为它使用了Node.js 20原生内置的fetchAPI进行网络请求实现了“零依赖”。检查命令node --version。Telegram频道已配置你的~/.openclaw/openclaw.json中必须已经正确配置了Telegram频道。这意味着你已经从BotFather那里获得了Bot Token并在配置中设置了token和allowFrom允许接收消息的Chat ID。这是插件能工作的基础。3.2 插件安装的两种方式方式一通过OpenClaw插件管理器安装推荐这是最简单的方法适合绝大多数用户。OpenClaw的插件系统支持从npm仓库直接安装。openclaw plugins install telegram-approval-buttons执行这个命令后OpenClaw会自动从npm下载该插件的最新版本并将其注册到插件系统中。通常它也会自动在配置文件中添加对应的条目并启用。实操心得安装后建议立刻运行openclaw plugins list来确认插件已出现在列表中并且状态是enabled。有时候网络问题可能导致安装不完整。方式二从源码安装适用于开发或测试特定版本如果你想贡献代码或者需要测试某个尚未发布的修复分支可以从GitHub克隆源码进行本地安装。git clone https://github.com/JairFC/openclaw-telegram-approval-buttons.git cd openclaw-telegram-approval-buttons # 如果需要可以在这里切换到某个分支或标签 # git checkout v1.2.3然后你需要手动编辑OpenClaw的配置文件告诉它从本地路径加载这个插件。打开你的~/.openclaw/openclaw.json文件找到或添加plugins部分{ plugins: { load: { paths: [ /绝对/路径/到/openclaw-telegram-approval-buttons ] } } }注意事项路径必须是绝对路径。使用这种方式时openclaw plugins list可能不会显示它但只要配置正确OpenClaw在启动时会加载它。对插件代码的任何修改都需要重启OpenClaw网关才能生效。3.3 核心配置详解连接插件与审批流安装插件只是第一步。最关键的是正确配置这包含两个独立但又必须协同工作的部分审批目标配置和插件自身配置。很多用户卡在这一步。第一部分配置审批请求发送到Telegram插件工作的前提是OpenClaw的审批请求必须被发送到Telegram频道。这是通过approvals.exec配置节来控制的。如果你的配置里没有这个或者目标不是Telegram那么插件根本“看”不到审批消息自然无法生效。打开~/.openclaw/openclaw.json添加或修改如下部分{ approvals: { exec: { enabled: true, // 必须为 true mode: targets, // 使用 targets 模式将审批定向到特定频道 targets: [ { channel: telegram, // 频道类型必须是 telegram to: YOUR_TELEGRAM_CHAT_ID // 这里填你的Telegram Chat ID } // 你可以在这里添加多个targets将审批同时发到不同地方 ] } } }第二部分配置插件本身接下来需要配置插件告诉它你的Bot Token和Chat ID这样它才能代表你的Bot去发送和编辑消息。配置通常在plugins.entries下。{ plugins: { entries: { telegram-approval-buttons: { enabled: true, // 确保启用 config: { botToken: YOUR_BOT_TOKEN, chatId: YOUR_TELEGRAM_CHAT_ID, staleMins: 10, // 可选审批过期时间分钟默认10 verbose: false // 可选开启详细日志调试时有用 } } } } }关键点解析botToken和chatId这是插件与你的Telegram Bot通信的凭证。chatId通常和上面approvals.exec.targets[0].to的值相同。配置解析顺序插件设计得很智能它会尝试自动发现这些配置。顺序是首先查找pluginConfig即上面手动配置的。如果没找到则尝试从channels.telegram的配置中读取token和allowFrom[0]。最后会检查环境变量TELEGRAM_BOT_TOKEN和TELEGRAM_CHAT_ID。如果以上都未找到插件将无法启动。如何获取YOUR_BOT_TOKEN和YOUR_TELEGRAM_CHAT_IDBot Token在Telegram中搜索BotFather与其对话使用/newbot命令创建一个新Bot或使用/mybots管理现有Bot。创建成功后BotFather会给你一串类似1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ的令牌这就是botToken。请妥善保管它等同于你的Bot密码。Chat ID有几种方法最简单在Telegram中搜索userinfobot向它发送任意消息它会回复你的用户IDUser ID。对于私聊Bot这个User ID就是chatId。通过日志先确保你的OpenClaw Telegram频道配置正确并运行。然后给你的Bot发一条消息。查看OpenClaw的日志 (openclaw logs --follow)你通常能在日志里看到类似Received message from chat ID: 123456789的信息。通过API在浏览器中访问https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates将YOUR_BOT_TOKEN替换为你的真实Token。然后给你的Bot发条消息再刷新这个页面你会在返回的JSON数据中找到message.chat.id字段。3.4 验证配置与重启服务配置完成后必须重启OpenClaw网关以使更改生效。openclaw gateway restart重启后在与你Bot的Telegram私聊或群组中发送命令/approvalstatus。如果一切配置正确插件会回复一个状态消息 Approval Buttons Status Telegram: chatId✓ · token✓ ✓ connected (your_bot_name) Slack: not configured Pending: 0 · Processed: 0 Uptime: 1m这个状态报告非常有用它告诉你Telegram配置检测通过✓。Bot连接成功并显示了你的Bot用户名。当前没有待处理Pending的审批总共处理过Processed0个。插件已运行了1分钟。如果你看到的是DISABLED — missing config说明插件没有找到必要的配置Token或Chat ID请根据上面的步骤仔细检查你的openclaw.json文件。4. 插件工作流程与核心环节实现4.1 消息拦截与转换的全过程让我们深入插件内部看看从AI触发审批到用户点击按钮整个数据流是如何工作的。触发审批当OpenClaw AI试图执行一个配置为需要审批的命令如exec时网关的审批系统被触发。生成审批请求网关创建一个包含唯一UUID、命令详情、请求者等信息的审批请求对象并将其格式化为一条文本消息。例如“ Exec approval requested for ‘ls -la‘ by user. UUID: 123e4567-e89b-12d3-a456-426614174000. Reply with /approve uuid allow-once|allow-always|deny”。插件拦截message_sending钩子网关准备将这条文本消息发送到配置的Telegram目标。在发送前message_sending事件被触发。telegram-approval-buttons插件监听此事件。解析与识别插件的approval-parser模块检查这条消息。它使用正则表达式匹配特定的模式如“Exec approval requested”、“UUID:”如果匹配成功则判定这是一条审批消息并提取出UUID、命令片段等关键数据。构造富消息message-formatter模块接手将提取的信息重新组织成更友好的格式例如使用更清晰的标题高亮命令并最关键的是——生成一个Telegram内联键盘Inline Keyboard对象。这个键盘通常包含三个按钮其callback_data被设置为类似approve:123e4567-e89b-12d3-a456-426614174000:allow-once的格式。发送与取消插件通过telegram-api模块使用Bot Token向指定的Chat ID发送这条带按钮的新消息。发送成功后插件会取消原文本消息的发送通过事件钩子提供的机制从而实现“替换”。状态跟踪插件将这条新消息的message_id、chat_id和过期时间戳记录到approval-store的内存存储中。用户交互用户在Telegram中看到带按钮的消息并点击其中一个如“允许一次”。回调处理Telegram向Bot发送一个callback_query。插件的telegram-api模块接收到此查询。它首先调用answerCallbackQuery向Telegram发送一个即时反馈如显示“已允许”的提示然后解析callback_data得到操作指令。模拟用户输入这是最关键的一步。插件本身并不直接调用OpenClaw的审批API。相反OpenClaw的Telegram驱动层会捕获到这个callback_query并根据其callback_data自动合成一条文本消息内容就是/approve 123e4567-e89b-12d3-a456-426614174000 allow-once然后将其注入到消息处理流中就像用户手动输入了一样。网关处理OpenClaw网关收到这条“合成”的文本命令其内置的审批处理器会识别并执行对应的审批操作允许或拒绝。更新消息状态审批完成后网关通常会通知结果。插件可能再次被触发或者通过其他机制获取到审批结果然后使用editMessageTextAPI 去更新原始的那条带按钮的消息移除按钮并显示“已允许”或“已拒绝”的结果。同时从approval-store中清理该记录。过期清理一个后台的定时任务会定期扫描approval-store将超时超过staleMins配置的记录标记为“已过期”并同样通过editMessageText更新对应的Telegram消息告知用户此审批已失效。4.2 核心代码逻辑浅析虽然我们不需要深入每一行代码但了解几个核心函数的逻辑有助于调试拦截判断 (index.ts):// 伪代码逻辑 on(‘message_sending‘, (event) { if (event.channel ! ‘telegram‘) return; // 只处理Telegram频道 if (!isApprovalMessage(event.text)) return; // 调用解析器判断 // 如果是审批消息则取消原事件发送按钮消息 event.cancel(); sendButtonizedMessage(event.text, event.to); });解析器 (approval-parser.ts):// 简化版的正则匹配示例 const APPROVAL_REGEX / Exec approval requested for ‘(.?)‘ by (.?)\. UUID: ([a-f0-9-])\./; function parseApproval(text: string): ApprovalInfo | null { const match text.match(APPROVAL_REGEX); if (!match) return null; return { command: match[1], requester: match[2], uuid: match[3], rawText: text }; }按钮构造 (message-formatter.ts):// 构造Telegram内联键盘 const keyboard: InlineKeyboardButton[][] [ [ { text: ‘✅ Allow Once‘, callback_data: approve:${uuid}:allow-once }, { text: ‘ Always Allow‘, callback_data: approve:${uuid}:allow-always } ], [ { text: ‘❌ Deny‘, callback_data: approve:${uuid}:deny } ] ];4.3 高级配置与Slack支持插件也支持Slack其原理与Telegram类似但使用的是Slack的Block Kit组件来构建按钮界面。配置上需要Slack Bot的OAuth Token和Channel ID。{ plugins: { entries: { telegram-approval-buttons: { enabled: true, config: { botToken: 123:ABC..., chatId: 123456789, slackBotToken: xoxb-your-slack-bot-token, // Slack Bot Token slackChannelId: C1234567890, // Slack Channel ID staleMins: 15, // 可以单独为Slack设置不同的超时 verbose: true // 调试时开启会在日志中打印详细过程 } } } } }Slack配置要点slackBotToken需要在Slack API网站创建一个Bot并安装到你的工作区获得xoxb-开头的Bot User OAuth Token。slackChannelIdSlack频道的ID不是名称。你可以在Slack网页版中右键点击频道标题 - “复制链接”链接末尾的那串字符就是Channel ID。Slack的审批消息会以“快捷方式”或“模态框”的形式出现具体取决于插件的实现。其回调处理同样依赖于OpenClaw Slack驱动将交互载荷转换为合成命令的能力。5. 实战排坑与经验总结即使按照指南操作也可能会遇到一些问题。下面是我在部署和使用过程中遇到的一些典型情况及解决方法。5.1 常见问题速查表问题现象可能原因排查步骤与解决方案安装插件后仍然收到纯文本审批消息1.approvals.exec配置错误或缺失。2. 配置未生效。1.首要检查运行openclaw config get approvals.exec查看当前配置。确保enabled: true,mode: targets且targets中包含channel: “telegram“。2. 检查配置文件路径是否正确 (~/.openclaw/openclaw.json)。3.重启网关任何配置修改后必须执行openclaw gateway restart。/approvalstatus命令无响应或报“未知命令”1. 插件未成功加载。2. 插件配置错误导致初始化失败。1. 运行openclaw plugins list确认telegram-approval-buttons状态为enabled。2. 检查OpenClaw日志 (openclaw logs --follow --tail50)查看启动时是否有插件加载错误。3. 确认插件配置plugins.entries部分格式正确特别是botToken和chatId是否有拼写错误或遗漏引号。按钮可以显示但点击后无任何反应1. Bot没有权限编辑消息或发送回调应答。2. OpenClaw的Telegram驱动版本过旧。1.私聊测试确保你在与Bot的私聊中测试。在群组中Bot可能需要“编辑自身消息”的管理员权限。2.更新驱动确保你的OpenClaw版本是最新的老版本可能不支持将callback_query转换为合成消息。3.查看日志点击按钮后查看OpenClaw日志看是否有关于回调处理的错误信息。按钮显示“已过期” (Expired)1. 用户点击按钮时审批请求已超时 (staleMins)。2. 插件与网关之间的状态同步问题。1. 增加staleMins配置值例如设为30给用户更长的响应时间。2. 检查系统时间是否准确。如果服务器时间与Telegram服务器时间偏差过大可能导致计时错误。3. 这是一个预期行为旨在清理悬而未决的请求。如果频繁发生考虑优化审批流程的提醒。插件日志显示DISABLED — missing config插件无法自动或手动找到botToken和chatId。1.显式配置最可靠的方法是在plugins.entries.telegram-approval-buttons.config中手动填写这两项。2.检查自动发现源确认channels.telegram配置节是否存在且包含正确的token和allowFrom。3.检查环境变量如果使用环境变量确保其已正确导出且在OpenClaw进程的环境中可用。5.2 性能与稳定性考量内存存储approval-store使用内存存储意味着如果OpenClaw网关进程重启所有待处理的审批状态都会丢失对应的按钮将失效。这对于短期运行或可容忍重启的环境没问题。如果需求严苛可以考虑为其添加一个简单的持久化层如写入临时文件但这会增加复杂性。网络依赖插件严重依赖Telegram Bot API的可用性。如果网络出现波动或Telegram API暂时不可用按钮发送可能会失败。插件设计了“优雅降级”如果发送按钮失败会放行原始文本消息。这保证了审批功能本身不中断只是体验降级。速率限制频繁触发审批可能会触及Telegram Bot API的速率限制。虽然单个用户场景下很难触发但在高强度自动化测试时需要注意。插件内部应实现简单的重试或退避机制。5.3 安全最佳实践Token保护botToken是最高机密。永远不要将其提交到公开的版本控制系统如Git。确保你的openclaw.json文件权限设置为仅当前用户可读 (chmod 600 ~/.openclaw/openclaw.json)。最小权限原则为你的Telegram Bot设置合理的权限。在群组中使用时只授予它“发送消息”和“编辑自身消息”的权限无需赋予其管理员所有权限。Chat ID验证确保chatId配置正确避免审批请求发送到错误的聊天可能泄露敏感命令信息。审批超时合理设置staleMins。太短可能导致用户来不及操作太长则可能让已遗忘的审批请求长期占用资源。10-30分钟是一个合理的范围。5.4 扩展思路这个插件提供了一个优秀的范式。你可以基于此思路进行扩展支持更多频道比如钉钉、企业微信、飞书等。只需要实现对应平台的API客户端和消息格式化器。自定义按钮与消息格式修改message-formatter.ts可以改变按钮的文字、排列甚至增加更多操作如“延迟审批”、“请求更多信息”。审批工作流增强与外部审批系统如JIRA, OAuth集成。例如点击“批准”后插件可以先去调用一个外部API进行二次验证然后再决定是否向OpenClaw发送批准指令。审计日志在插件中增加钩子将所有审批操作谁、何时、批准/拒绝了什么命令记录到外部日志系统或数据库以满足合规性要求。这个openclaw-telegram-approval-buttons插件虽然体积不大但设计精巧切实解决了一个具体的用户体验问题。它展示了如何通过OpenClaw的插件体系以非侵入的方式扩展和优化核心功能。通过正确的配置和理解其工作流程你可以极大地提升在Telegram中管理AI自动化操作的安全性和便捷性。如果在使用中遇到任何问题仔细查阅日志和上述排查指南大部分问题都能迎刃而解。