ClawdBot 开发指南：CLI、Webhook 及自定义 Agent 扩展实践

你还可以用 CLI 快速验证模型响应：

clawdbot models chat --model "vllm/Qwen3-4B-Instruct-2507" "用三句话解释什么是 vLLM？" 

它会直接调用后端 vLLM 接口，返回结构化响应，省去手动构造 HTTP 请求的麻烦。这种'命令即调试'的设计，极大缩短了模型集成与验证周期。

2. Webhook：让 ClawdBot 成为你工作流中的'智能插件'

CLI 是你主动调用 ClawdBot 的方式，而 Webhook 则是让它被动响应外部世界的接口。它不是简单的 HTTP 回调，而是一套标准化、可过滤、可重试的事件总线，让你能把 ClawdBot 轻松嵌入到任何已有系统中。

2.1 Webhook 基础：接收与响应一条结构化消息

ClawdBot 默认在 /webhook 路径监听 POST 请求。只要发送符合规范的 JSON，它就能解析、路由、执行并返回结果。

一个最简示例（模拟 Telegram 消息）：

curl -X POST http://localhost:7860/webhook \ 
-H "Content-Type: application/json" \ 
-d '{ "source": "telegram", "user_id": "123456789", "message": "今天北京天气怎么样？", "channel": "private" }' 

ClawdBot 会自动识别这是查询类请求，调用内置天气 Agent，再用主模型润色回复，最终返回：

{
  "reply": "北京今日晴，气温 -2°C ~ 6°C，西北风 3 级，空气质量良。",
  "agent_used": "weather",
  "latency_ms": 427
}

注意两个关键字段：agent_used 表明哪个子模块处理了请求，latency_ms 记录端到端耗时——这对调试和性能优化至关重要。

2.2 事件过滤：只接收你关心的消息类型

生产环境中，你不会希望所有消息都涌向 ClawdBot。ClawdBot 支持基于 JSONPath 的请求预过滤。例如，只想处理来自特定群组、且包含 @bot 的消息：

{
  "webhook": {
    "filter": "$.channel == 'group' && $.message contains '@clawdbot'"
  }
}

这个过滤器在请求进入业务逻辑前就生效，无效请求直接返回 403 Forbidden，不消耗 GPU 资源，也不触发日志记录。它让 Webhook 不再是'来者不拒'的管道，而是一个有判断力的守门人。

2.3 可靠投递：失败重试与死信队列

网络不稳定、服务临时不可用是常态。ClawdBot 的 Webhook 内置重试策略：默认 3 次指数退避重试（1s, 2s, 4s），超时阈值可配置。若全部失败，则自动将原始请求存入本地 SQLite 死信队列（/app/data/dead-letters.db）。

你可以随时用 CLI 查看积压：

clawdbot webhook dead-letters list --limit 5 

并选择性重放：

clawdbot webhook dead-letters replay --id "dl_abc123" 

这种'尽力而为 + 可追溯'的设计，让 Webhook 在真实业务场景中真正可靠，而不是一个脆弱的胶水层。

3. 自定义 Agent：从'调用模型'升级为'构建智能体'

ClawdBot 的核心抽象不是'模型'，而是 'Agent'。一个 Agent 是一个具备明确职责、独立生命周期、可配置输入输出的智能单元。它可能是调用天气 API 的小工具，也可能是编排多个模型协作的复杂工作流。ClawdBot 不强制你用某种框架写 Agent，而是提供标准协议与运行时支持。

3.1 Agent 协议：三步定义一个可运行的智能体

要让 ClawdBot 认识你的 Agent，只需实现三个约定：

1. 描述文件 agent.yaml（放在 /app/agents/my-weather/ 下）：

name: weather
version: 1.0.0
description: "Query current weather by city name"
input_schema:
  type: object
  properties:
    city: { type: string, description: "City name in Chinese or English" }
output_schema:
  type: object
  properties:
    temperature: { type: number }
    condition: { type: string }
    humidity: { type: number }

2. 执行脚本 run.py（Python 示例，也可用 Bash/Node.js）：

#!/usr/bin/env python3
import sys
import json
import requests

data = json.load(sys.stdin)
city = data.get("city", "Beijing")
# 调用公开天气 API（此处简化）
resp = requests.get(f"https://api.example.com/weather?q={city}")
result = resp.json()
print(json.dumps({
  "temperature": result["temp"],
  "condition": result["weather"],
  "humidity": result["humidity"]
}))

3. 权限声明 permissions.json（声明所需外部访问）：

{
  "network": ["https://api.example.com"],
  "files": ["/tmp/weather-cache.json"]
}

ClawdBot 启动时会自动扫描 /app/agents/ 目录，加载所有符合协议的 Agent，并将其注册为可调用服务。

3.2 Agent 编排：用 YAML 定义多步智能工作流

单个 Agent 能力有限，但多个 Agent 可以串联成强大工作流。ClawdBot 支持声明式编排，用 YAML 描述执行顺序、条件分支与数据流转。

例如，一个'图片翻译+OCR+汇率查询'复合 Agent：

# /app/agents/multilingual-translation.yaml
name: multilingual-translation
steps:
  - id: ocr
    agent: paddleocr
    input: "{{ .message.image_url }}"
  - id: translate
    agent: libretranslate
    input: "{{ .steps.ocr.text }}"
    if: "{{ .steps.ocr.text | len > 0 }}"
  - id: fx
    agent: currency
    input: "{{ .steps.translate.result }}"
    if: "{{ .steps.translate.result | contains 'USD' }}"
    output: "{{ .steps.translate.result }} ({{ .steps.fx.rate }})"

ClawdBot 运行时会自动解析依赖关系，按序执行，并将上一步输出注入下一步输入。你不用写一行协调代码，就能获得一个具备条件判断与数据流动的智能体。

3.3 Agent 调试：在 CLI 中像调试函数一样调试智能体

开发 Agent 最痛苦的是反复部署、重启、测试。ClawdBot CLI 提供了 agent run 命令，让你在开发阶段直接调用任意 Agent，传入模拟输入，实时查看输出与日志：

clawdbot agent run --agent weather --input '{"city": "Shanghai"}' 

输出包含：

• 执行耗时与内存占用
• 标准输出与标准错误流
• 返回的结构化结果（自动格式化为 JSON）
• 若失败，显示完整 traceback

这相当于为每个 Agent 提供了一个独立的 REPL 环境，彻底告别'改完代码 → 构建镜像 → 重启容器 → 发送测试消息'的漫长循环。

4. 与 MoltBot 的协同实践：打造你的私有 Telegram 全能助手

ClawdBot 本身不绑定任何通信渠道，但它与 MoltBot 这类专注 Telegram 的开源机器人天然互补。MoltBot 解决'消息收发与多模态预处理'，ClawdBot 解决'智能决策与复杂任务编排'。二者结合，你能快速构建一个完全私有、功能远超官方机器人的 Telegram 助手。

4.1 架构分工：各司其职，避免重复造轮子

这种分工让 MoltBot 保持轻量、稳定、易部署；ClawdBot 则专注智能、可扩展、可定制。它们之间只通过标准 HTTP Webhook 通信，耦合度极低。

4.2 实战集成：用 ClawdBot 增强 MoltBot 的'理解力'

MoltBot 收到一条消息后，通常直接调用翻译或查询服务。但有些需求它无法满足，比如：'把刚才我发的三张产品图，分别生成英文电商文案，风格要专业简洁'。

这时，MoltBot 可以把这条复杂指令转发给 ClawdBot：

// MoltBot 发送给 ClawdBot 的 Webhook
{
  "source": "moltbot",
  "user_id": "123456789",
  "task": "generate_product_copy",
  "images": ["https://...", "https://...", "https://..."],
  "style": "professional, concise, e-commerce"
}

ClawdBot 接收到后，触发一个自定义 Agent：

• 第一步：调用内置 vision Agent（封装 LLaVA）分析每张图，提取产品特征
• 第二步：调用 text-generation Agent（Qwen3-4B）根据特征生成文案
• 第三步：调用 multilingual Agent 翻译成目标语言
• 第四步：汇总结果，格式化为 Telegram 友好 Markdown

整个流程对 MoltBot 透明，它只负责'收'和'发'，真正的'思考'由 ClawdBot 完成。你得到的不是一个翻译机器人，而是一个能理解图像、生成文案、跨语言表达的 AI 助手。

4.3 部署建议：一套硬件，两个容器，零配置协同

两者都支持 Docker 部署，且资源需求互补：

• MoltBot：CPU 密集型（Whisper/PaddleOCR），内存占用低（~500MB），树莓派 4 可跑
• ClawdBot：GPU 密集型（vLLM），内存占用高（~2GB+），需 NVIDIA GPU

推荐部署方式：

# docker-compose.yml
services:
  moltbot:
    image: moltbot/moltbot:latest
    restart: unless-stopped
    environment:
      - TELEGRAM_BOT_TOKEN=xxx
      - CLAWDBOT_WEBHOOK_URL=http://clawdbot:7860/webhook
    depends_on:
      - clawdbot
  clawdbot:
    image: clawdbot/clawdbot:latest
    restart: unless-stopped
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

MoltBot 启动时自动读取 CLAWDBOT_WEBHOOK_URL 环境变量，将复杂请求转发过去。你只需维护一份 docker-compose.yml，两个服务自动发现、自动通信、自动容错。

5. 总结：从工具使用者，变成 AI 助手的架构师

ClawdBot CLI、Webhook 和自定义 Agent，这三者共同构成了一个面向开发者的 AI 助手构建范式：

• CLI 是你的控制中枢：它把系统状态、设备信任、模型管理这些底层细节，封装成一句命令就能完成的操作。你不再需要记住一堆配置路径和端口，而是用自然语义与系统对话。
• Webhook 是你的神经接口：它让 ClawdBot 脱离'被调用'的被动角色，成为你现有工作流中一个可编程、可观察、可恢复的智能节点。无论是 Telegram、Discord 还是内部 CRM，都能无缝接入。
• 自定义 Agent 是你的思维扩展：它打破了'大模型万能'的幻觉，承认专用能力的价值。OCR、天气、汇率、知识库……每个 Agent 都是你业务逻辑的具象化，而 ClawdBot 提供的不是 SDK，而是一个运行时、一个协议、一个调试环境。

这条路的终点，不是部署一个机器人，而是建立一套属于你自己的 AI 能力基础设施。它不依赖厂商，不担心停服，不泄露数据，且随着你不断添加 Agent，它的能力只会越来越贴合你的实际需求。

当你第一次用 clawdbot agent run 调通自己写的天气 Agent，当你看到 MoltBot 转发的图片请求被 ClawdBot 完美解析并生成文案，你就不再是 AI 工具的使用者，而是真正开始设计、构建、拥有属于自己的智能体。