ClawdBot 插件开发:为 Telegram 机器人添加新快捷命令的实践
1. ClawdBot 是什么:一个可扩展的本地 AI 助手底座
ClawdBot 不是一个开箱即用的'功能型机器人',而是一个面向开发者设计的可插拔 AI 网关平台。它不像传统 Telegram Bot 那样只做单一任务,而是像一个轻量级的'AI 操作系统'——你可以在自己的设备(笔记本、树莓派、云服务器)上运行它,然后按需加载不同能力模块:文本推理、多模态理解、消息路由、频道接入、快捷命令等。
介绍 ClawdBot 插件开发,旨在为 Telegram 机器人扩展功能。ClawdBot 是基于 vLLM 的本地 AI 网关平台,支持模块化插件机制。文章通过编写 /summary 文本摘要插件为例,演示了从目录结构创建、核心逻辑编写、配置文件声明到加载验证的全过程。进阶部分涵盖多模态输入支持、限流缓存机制以及与 MoltBot 联动。最后介绍了 Web 控制台调试、文档编写及 Docker 打包发布方法。通过插件化开发,开发者可快速组合 AI 能力,无需深入底层模型细节即可实现复杂功能。
ClawdBot 不是一个开箱即用的'功能型机器人',而是一个面向开发者设计的可插拔 AI 网关平台。它不像传统 Telegram Bot 那样只做单一任务,而是像一个轻量级的'AI 操作系统'——你可以在自己的设备(笔记本、树莓派、云服务器)上运行它,然后按需加载不同能力模块:文本推理、多模态理解、消息路由、频道接入、快捷命令等。
它的核心定位很清晰:把大模型能力封装成可编排的服务单元,再通过标准化接口暴露给各类前端渠道(Telegram、Web UI、CLI、API)。这正是它能支撑 MoltBot 这类复杂翻译机器人的底层原因——不是靠硬编码所有功能,而是靠插件机制动态组合能力。
ClawdBot 的后端由 vLLM 提供高性能推理支持,这意味着它不依赖云端 API,所有模型调用都在本地完成,响应快、隐私强、无调用限制。你看到的 /weather、/fx、/wiki 这些命令,并非写死在 Telegram 代码里,而是作为独立插件注册进 ClawdBot 的命令总线,由统一的路由层分发执行。
换句话说:ClawdBot 是'引擎',MoltBot 是'跑车',而你写的每一个新命令,就是给这辆跑车加装的新功能模块——比如一键生成会议纪要、自动归档群聊关键词、根据截图查商品价格……只要你想得到,就能插得上。
很多开发者第一次接触 ClawdBot 时会疑惑:'我已经有 Telegram Bot Token,为什么不直接写个 Python 脚本监听消息?' 答案很简单:可维护性、复用性、隔离性。
/weather 的城市解析逻辑时,只需改 weather-plugin 目录下的代码,不影响翻译、OCR 或汇率模块;更重要的是,ClawdBot 的插件系统采用声明式注册 + 函数式执行模式:你不需要关心消息怎么从 Telegram 接入、怎么序列化、怎么鉴权——你只用专注写一个干净的 Python 函数,接收结构化输入,返回结构化输出。其余所有胶水逻辑,都由框架兜底。
这种设计让'加一个新命令'这件事,从过去需要改路由、加 handler、修测试、部署服务的 2 小时工程,压缩成:新建文件 → 写 20 行函数 → 注册配置 → clawdbot plugins reload —— 全程 5 分钟,且零停机。
/summary 插件我们以一个真实高频需求为例:为群聊中长消息自动生成摘要。用户发送一段 500 字的产品需求描述,希望机器人一键返回 3 句精炼要点。
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的子目录,将其识别为插件包。
# ~/.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 服务打通。
在 ~/.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 表示默认启用。保存文件后,在终端执行:
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确认)。
写完基础功能只是开始。真正好用的插件,往往藏在细节里。
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 已有的多模态能力复用。
本地 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
import hashlib
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 小时
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
这种'插件即模块'的设计,让整个生态形成正向循环:你写的插件,别人也能拿来二次开发;别人写的插件,你也能快速集成——这才是开源协作的真实力量。
开发完成不等于结束。一个成熟的插件,还需要经过调试、文档、打包三步。
ClawdBot 的 Web UI(通过 clawdbot dashboard 访问)不仅是个配置面板,更是强大的调试中心:
execute 并传入模拟参数;summary 关键字,实时观察报错堆栈;比起反复重启服务、切窗口、发消息验证,这种方式效率提升 5 倍以上。
在 ~/.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 翻译机器人——无需任何额外配置。
ClawdBot 的插件开发,不是教你写更多代码,而是教你用更少的代码,组合出更强的能力。它把模型调用、消息路由、权限控制、限流缓存、日志监控这些'脏活累活'全部封装好,只留下最干净的接口让你发挥创意。
你不需要成为 vLLM 专家,也能调用 Qwen3; 你不需要懂 Telegram Bot API,也能让命令在群聊中生效; 你不需要研究 OCR 原理,也能让图片变文字再变摘要。
这正是现代 AI 工程的进化方向:从'造轮子'转向'搭积木',从'写代码'转向'编排能力'。
当你写下第一个 plugin = SummaryPlugin({}),你就已经站在了 AI 应用开发的快车道上——接下来,是给你的机器人加一个 /todo 待办管理?还是 /code 代码解释器?又或者 /translate 图片内文字翻译?选择权,完全在你手中。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
使用加密算法(如AES、TripleDES、Rabbit或RC4)加密和解密文本明文。 在线工具,加密/解密文本在线工具,online
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online