跳到主要内容 ClawdBot 插件开发：为 Telegram 机器人添加快捷命令 | 极客日志
Python AI 算法
ClawdBot 插件开发：为 Telegram 机器人添加快捷命令 介绍 ClawdBot 插件开发，旨在为 Telegram 机器人扩展功能。ClawdBot 是基于 vLLM 的本地 AI 网关平台，支持模块化插件机制。文章通过编写 /summary 文本摘要插件为例，演示了从目录结构创建、核心逻辑编写、配置文件声明到加载验证的全过程。进阶部分涵盖多模态输入支持、限流缓存机制以及与 MoltBot 联动。最后介绍了 Web 控制台调试、文档编写及 Docker 打包发布方法。通过插件化开发，开发者可快速组合 AI 能力，无需深入底层模型细节即可实现复杂功能。
筑梦师 发布于 2026/4/6 更新于 2026/4/16 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）
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)
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 = f"""你是一名专业文案编辑，请对以下内容生成 3 条要点式摘要，每条不超过 20 字，用中文回答：
{text}
摘要："""
try :
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 = SummaryPlugin({})
这段代码做了四件事：
① 定义插件类，继承 Plugin 基类；
② 重写 describe() 告诉系统这个命令叫什么、怎么用；
③ 重写 execute() 实现核心逻辑，自动处理消息来源、截断、提示词构造、模型调用；
④ 导出 plugin 实例，作为 ClawdBot 的加载入口。
注意：ctx.llm.chat(...) 是 ClawdBot 提供的统一模型调用接口，你无需关心模型地址、API Key、重试逻辑——它已与你的 clawdbot.json 中配置的 vLLM 服务打通。
3.3 编写插件配置（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 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 自动提取摘要'。
media = ctx.get_media_file()
if media and media.mime_type in ["application/pdf" , "image/png" , "image/jpeg" ]:
text = await ctx.ocr.extract_text(media.path)
if not text.strip():
return CommandResult.error("未能从文件中识别出有效文字" )
这样，用户发一张会议白板照片，或拖入一份 PRD PDF，都能一键生成摘要——而你几乎不用新增模型代码，全靠 ClawdBot 已有的多模态能力复用。
4.2 添加缓存与限流：保护你的本地模型 本地 vLLM 资源有限，不能任由用户高频刷 /summary。ClawdBot 提供了开箱即用的限流器：
from clawdbot.utils.rate_limit import RateLimiter
class SummaryPlugin (Plugin ):
def __init__ (self, config: Dict [str , Any ] ):
super ().__init__(config)
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 )
4.3 与 MoltBot 无缝联动：复用现有能力 MoltBot 的 /wiki 和 /weather 插件，其实就放在 ~/.clawdbot/plugins/wiki/ 和 ~/.clawdbot/plugins/weather/ 下。你可以直接参考它们的写法，甚至 import 其工具函数：
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 的插件详情页，用户点开就能看懂怎么用。
如果你希望把 `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 图片内文字翻译？选择权，完全在你手中。
微信扫一扫，关注极客日志 微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具 加密/解密文本 使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
curl 转代码 解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
