ClawdBot插件开发：为Telegram机器人添加新快捷命令的实践

ClawdBot插件开发：为Telegram机器人添加新快捷命令的实践

1. ClawdBot 是什么：一个可扩展的本地AI助手底座

ClawdBot 不是一个开箱即用的“功能型机器人”，而是一个面向开发者设计的可插拔AI网关平台。它不像传统 Telegram Bot 那样只做单一任务，而是像一个轻量级的“AI操作系统”——你可以在自己的设备（笔记本、树莓派、云服务器）上运行它，然后按需加载不同能力模块：文本推理、多模态理解、消息路由、频道接入、快捷命令等。

它的核心定位很清晰：把大模型能力封装成可编排的服务单元，再通过标准化接口暴露给各类前端渠道（Telegram、Web UI、CLI、API）。这正是它能支撑 MoltBot 这类复杂翻译机器人的底层原因——不是靠硬编码所有功能，而是靠插件机制动态组合能力。

ClawdBot 的后端由 vLLM 提供高性能推理支持，这意味着它不依赖云端 API，所有模型调用都在本地完成，响应快、隐私强、无调用限制。你看到的 /weather、/fx、/wiki 这些命令，并非写死在 Telegram 代码里，而是作为独立插件注册进 ClawdBot 的命令总线，由统一的路由层分发执行。

换句话说：ClawdBot 是“引擎”，MoltBot 是“跑车”，而你写的每一个新命令，就是给这辆跑车加装的新功能模块——比如一键生成会议纪要、自动归档群聊关键词、根据截图查商品价格……只要你想得到，就能插得上。

2. 为什么是插件开发：告别硬编码，拥抱模块化扩展

很多开发者第一次接触 ClawdBot 时会疑惑：“我已经有 Telegram Bot Token，为什么不直接写个 Python 脚本监听消息？”
答案很简单：可维护性、复用性、隔离性。

• 可维护性：当你要修改 /weather 的城市解析逻辑时，只需改 weather-plugin 目录下的代码，不影响翻译、OCR 或汇率模块；
• 复用性：同一个天气插件，既能被 Telegram 渠道调用，也能被 Web 控制台或 CLI 命令复用，无需重复实现；
• 隔离性：某个插件崩溃（比如 OCR 模型加载失败），不会导致整个机器人宕机，ClawdBot 会自动降级并记录日志。

更重要的是，ClawdBot 的插件系统采用声明式注册 + 函数式执行模式：你不需要关心消息怎么从 Telegram 接入、怎么序列化、怎么鉴权——你只用专注写一个干净的 Python 函数，接收结构化输入，返回结构化输出。其余所有胶水逻辑，都由框架兜底。

这种设计让“加一个新命令”这件事，从过去需要改路由、加 handler、修测试、部署服务的 2 小时工程，压缩成：新建文件 → 写 20 行函数 → 注册配置 → clawdbot plugins reload —— 全程 5 分钟，且零停机。

3. 动手实践：从零编写一个 /summary 插件

我们以一个真实高频需求为例：为群聊中长消息自动生成摘要。用户发送一段 500 字的产品需求描述，希望机器人一键返回 3 句精炼要点。

3.1 创建插件目录结构

ClawdBot 插件必须放在 ~/.clawdbot/plugins/ 下（或通过 CLAWDBOT_PLUGINS_DIR 环境变量指定）。我们新建一个 summary 插件：

mkdir -p ~/.clawdbot/plugins/summary touch ~/.clawdbot/plugins/summary/__init__.py touch ~/.clawdbot/plugins/summary/main.py 

提示：ClawdBot 会自动扫描该目录下含 __init__.py 的子目录，将其识别为插件包。

3.2 编写核心逻辑（main.py）

# ~/.clawdbot/plugins/summary/main.py from typing import Dict, Any, Optional from clawdbot.plugins import Plugin, CommandContext, CommandResult class SummaryPlugin(Plugin): def __init__(self, config: Dict[str, Any]): super().__init__(config) # 可从 config 读取模型参数、超时设置等 self.model = config.get("model", "vllm/Qwen3-4B-Instruct-2507") self.max_length = config.get("max_length", 300) def describe(self) -> Dict[str, str]: return { "name": "summary", "description": "为长文本生成简洁摘要（支持中文）", "usage": "/summary <文本> 或 回复一条消息后输入 /summary" } async def execute(self, ctx: CommandContext) -> CommandResult: # 获取原始文本：优先取回复的消息内容，其次取命令后跟随的文本 text = ctx.get_reply_text() or ctx.get_arg_text() if not text or len(text.strip()) < 30: return CommandResult.error("请提供至少 30 字以上的文本，或回复一条长消息后输入 /summary") if len(text) > self.max_length: text = text[:self.max_length] + "...（已截断）" # 构造提示词（Prompt） prompt = f"""你是一名专业文案编辑，请对以下内容生成 3 条要点式摘要，每条不超过 20 字，用中文回答： {text} 摘要：""" try: # 调用 ClawdBot 内置的模型推理接口（自动路由到 vLLM） response = await ctx.llm.chat( model=self.model, messages=[{"role": "user", "content": prompt}], temperature=0.3, max_tokens=128 ) summary_text = response.choices[0].message.content.strip() return CommandResult.success(summary_text) except Exception as e: return CommandResult.error(f"摘要生成失败：{str(e)[:50]}...") # 必须导出 plugin 实例，ClawdBot 才能加载 plugin = SummaryPlugin({}) 

这段代码做了四件事：
① 定义插件类，继承 Plugin 基类；
② 重写 describe() 告诉系统这个命令叫什么、怎么用；
③ 重写 execute() 实现核心逻辑，自动处理消息来源、截断、提示词构造、模型调用；
④ 导出 plugin 实例，作为 ClawdBot 的加载入口。

注意：ctx.llm.chat(...) 是 ClawdBot 提供的统一模型调用接口，你无需关心模型地址、API Key、重试逻辑——它已与你的 clawdbot.json 中配置的 vLLM 服务打通。

3.3 编写插件配置（plugin.yaml）

在 ~/.clawdbot/plugins/summary/plugin.yaml 中声明元信息：

# ~/.clawdbot/plugins/summary/plugin.yaml name: summary version: "0.1.0" author: "your-name" description: "为长文本生成简洁摘要" enabled: true commands: - name: summary aliases: ["sum", "摘要"] description: "生成文本摘要" scope: ["private", "group", "supergroup"] 

• scope 指定该命令可在哪些场景使用（私聊、普通群、超级群）；
• aliases 支持多个别名，用户输 /sum 或 /摘要 同样生效；
• enabled: true 表示默认启用。

3.4 加载并验证插件

保存文件后，在终端执行：

clawdbot plugins reload 

你会看到类似输出：

🦞 Clawdbot 2026.1.24-3 — Reloading plugins... Loaded plugin 'summary' (0.1.0) with commands: [/summary, /sum, /摘要] 

接着，打开 Telegram，随便发一段话（比如产品需求文档节选），然后回复这条消息输入 /summary，几秒后就会收到结构清晰的摘要结果。

成功标志：命令出现在 /help 列表中，且能正常返回结果；
❌ 常见问题：plugin.yaml 格式错误、main.py 语法错误、模型未就绪（可用 clawdbot models list 确认）。

4. 进阶技巧：让插件更智能、更健壮

写完基础功能只是开始。真正好用的插件，往往藏在细节里。

4.1 支持多模态输入：不只是文字

ClawdBot 的 CommandContext 对象还提供了 ctx.get_media_file() 方法，可获取用户发送的图片、语音、PDF 等附件。我们可以轻松扩展 /summary 插件，让它支持“上传 PDF 自动提取摘要”。

只需在 execute() 开头加几行：

# 检查是否上传了文件 media = ctx.get_media_file() if media and media.mime_type in ["application/pdf", "image/png", "image/jpeg"]: # 调用内置 OCR 或 PDF 解析服务（ClawdBot 已集成 PaddleOCR） text = await ctx.ocr.extract_text(media.path) if not text.strip(): return CommandResult.error("未能从文件中识别出有效文字") # 后续仍走原有摘要逻辑... 

这样，用户发一张会议白板照片，或拖入一份 PRD PDF，都能一键生成摘要——而你几乎不用新增模型代码，全靠 ClawdBot 已有的多模态能力复用。

4.2 添加缓存与限流：保护你的本地模型

本地 vLLM 资源有限，不能任由用户高频刷 /summary。ClawdBot 提供了开箱即用的限流器：

# 在 main.py 中添加 from clawdbot.utils.rate_limit import RateLimiter class SummaryPlugin(Plugin): def __init__(self, config: Dict[str, Any]): super().__init__(config) # 每用户每 60 秒最多调用 3 次 self.limiter = RateLimiter("summary_per_user", window=60, limit=3) async def execute(self, ctx: CommandContext) -> CommandResult: # 检查限流 if not await self.limiter.allow(ctx.user_id): return CommandResult.error("操作太频繁，请 60 秒后再试") # ...原有逻辑 

同样，摘要结果也可缓存（基于文本哈希），避免重复计算：

from clawdbot.utils.cache import get_cache cache = get_cache("summary") cache_key = hashlib.md5(text.encode()).hexdigest() cached = await cache.get(cache_key) if cached: return CommandResult.success(cached) # 执行模型推理... await cache.set(cache_key, summary_text, expire=3600) # 缓存 1 小时 

4.3 与 MoltBot 无缝联动：复用现有能力

MoltBot 的 /wiki 和 /weather 插件，其实就放在 ~/.clawdbot/plugins/wiki/ 和 ~/.clawdbot/plugins/weather/ 下。你可以直接参考它们的写法，甚至 import 其工具函数：

# 在 summary/main.py 中复用天气插件的地理解析逻辑 try: from weather.utils import parse_location location = parse_location("上海浦东") except ImportError: location = None 

这种“插件即模块”的设计，让整个生态形成正向循环：你写的插件，别人也能拿来二次开发；别人写的插件，你也能快速集成——这才是开源协作的真实力量。

5. 调试与发布：从本地实验到团队共享

开发完成不等于结束。一个成熟的插件，还需要经过调试、文档、打包三步。

5.1 使用 Web 控制台实时调试

ClawdBot 的 Web UI（通过 clawdbot dashboard 访问）不仅是个配置面板，更是强大的调试中心：

• 进入 Plugins → Summary 页面，可手动触发 execute 并传入模拟参数；
• 查看 Logs → Plugin Logs，筛选 summary 关键字，实时观察报错堆栈；
• 在 Models → Test Chat 中，直接测试你用的提示词效果，快速迭代 prompt 工程。

比起反复重启服务、切窗口、发消息验证，这种方式效率提升 5 倍以上。

5.2 编写用户友好的帮助文档

在 ~/.clawdbot/plugins/summary/README.md 中写一段简明说明：

# Summary 插件 为长文本、PDF、图片生成精准摘要。 ## 使用方式 - 私聊中直接发送：`/summary 这是一段很长的需求描述...` - 在群聊中，先发送文字/图片，再回复 `/summary` - 支持中文，推荐输入 100–800 字内容 ## 配置项（可选） 在 `plugin.yaml` 中添加： ```yaml config: model: "vllm/Qwen3-4B-Instruct-2507" max_length: 500 

 ClawdBot 会自动将此 README 渲染到 Web UI 的插件详情页，用户点开就能看懂怎么用。 ### 5.3 打包为独立镜像（可选） 如果你希望把 `summary` 插件和 MoltBot 一起打包成 Docker 镜像分发，只需在 `Dockerfile` 中加入： ```dockerfile COPY ~/.clawdbot/plugins/summary /app/plugins/summary RUN chmod -R 755 /app/plugins/summary 

然后构建镜像，其他人 docker run -p 7860:7860 moltbot-summary 即可获得预装摘要功能的 Telegram 翻译机器人——无需任何额外配置。

6. 总结：插件开发的本质，是能力的乐高化

ClawdBot 的插件开发，不是教你写更多代码，而是教你用更少的代码，组合出更强的能力。它把模型调用、消息路由、权限控制、限流缓存、日志监控这些“脏活累活”全部封装好，只留下最干净的接口让你发挥创意。

你不需要成为 vLLM 专家，也能调用 Qwen3；
你不需要懂 Telegram Bot API，也能让命令在群聊中生效；
你不需要研究 OCR 原理，也能让图片变文字再变摘要。

这正是现代 AI 工程的进化方向：从“造轮子”转向“搭积木”，从“写代码”转向“编排能力”。

当你写下第一个 plugin = SummaryPlugin({})，你就已经站在了 AI 应用开发的快车道上——接下来，是给你的机器人加一个 /todo 待办管理？还是 /code 代码解释器？又或者 /translate 图片内文字翻译？选择权，完全在你手中。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 ZEEKLOG星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。