OpenClaw 集成 Telegram 机器人开发指南

OpenClaw 与 Telegram 机器人集成

OpenClaw 提供了强大的 Telegram Bot 集成能力，通过统一的 message 工具接口，可以轻松实现消息收发、群组管理、媒体处理等功能。本案例将详细介绍如何通过 OpenClaw 构建功能完整的 Telegram Bot。

前置准备

环境要求

• OpenClaw 已正确安装并配置
• Telegram Bot Token（通过 @BotFather 获取）
• 公网可访问的服务器（用于接收 Webhook）

核心概念

OpenClaw 的 message 工具是 Telegram 集成的核心接口，支持多种操作：

• send：发送文本、媒体、文件
• broadcast：批量发送消息
• reactions：消息反应（表情回应）
• typing：显示输入状态
• channels：频道和群组管理

Bot 创建

步骤 1：在 Telegram 创建 Bot

打开 Telegram，搜索 @BotFather 并保存返回的 Token。

Token 格式通常为 <bot_id>:<token_string>，例如：1234567890:ABCdefGHIjklMNOpqrsTUVwxyz。

创建流程如下：

1. 用户发送 /newbot
2. BotFather 回复：输入 Bot 名称（如 MyAwesomeBot）
3. BotFather 回复：输入 Bot 用户名（必须以 bot 结尾，如 MyAwesome_bot）
4. BotFather 返回：✅ Bot 创建成功！并提供 Token

步骤 2：配置 OpenClaw

在 OpenClaw 的配置文件中添加 Telegram 凭据：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "bots": {
        "default": {
          "token": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
          "name": "MyAwesomeBot"
        }
      }
    }
  }
}

步骤 3：验证 Bot 状态

使用 OpenClaw 检查 Bot 连接状态。你可以询问 Claude 或直接调用工具查询：

{"action":"status","accountId":"default"}

Webhook 配置

为什么需要 Webhook？

Webhook 允许 Telegram 服务器主动将用户消息推送到你的 OpenClaw 服务器，实现实时消息接收，相比轮询更高效。

步骤 1：准备 Webhook 服务器

确保 OpenClaw Gateway 服务正在运行：

# 检查 Gateway 状态
openclaw gateway status
# 如果未启动，启动 Gateway
openclaw gateway start

步骤 2：配置 Webhook URL

Webhook URL 格式通常为：

https://your-domain.com/webhook/telegram/<bot_token_hash>

或使用 OpenClaw 提供的默认路径：

https://your-domain.com/api/telegram/webhook

步骤 3：注册 Webhook

OpenClaw 会自动处理 Webhook 注册。如果需要手动配置：

{"action":"setWebhook","url":"https://your-domain.com/api/telegram/webhook","accountId":"default"}

步骤 4：验证 Webhook

测试 Webhook 是否正常工作：用户在 Telegram 发送消息给 Bot → Telegram 推送 POST 请求到 Webhook URL → OpenClaw 接收并处理 → Claude 通过消息历史看到用户消息。

Webhook 安全配置

建议设置 Secret Token 以验证请求来源：

{
  "webhook": {
    "secretToken": "your-secret-token-here",
    "allowedUpdates": ["message", "edited_message", "callback_query", "inline_query"]
  }
}

消息处理

接收消息

当用户发送消息给 Bot 时，OpenClaw 会自动接收并通过消息流呈现给 Claude。

消息结构示例

{
  "update_id": 123456789,
  "message": {
    "message_id": 1,
    "from": {"id": 123456789, "is_bot": false, "first_name": "User"},
    "chat": {"id": 123456789, "type": "private"},
    "date": 1708790400,
    "text": "Hello, Bot!"
  }
}

发送文本消息

使用 OpenClaw 的 message 工具发送消息：

{"action":"send","target":"123456789","message":"你好！我是 OpenClaw Bot，很高兴为你服务！"}

发送 Markdown 格式消息

{
  "action": "send",
  "target": "123456789",
  "message": "**加粗文本**\n_斜体文本_\n`代码块`\n[链接](https://example.com)",
  "contentType": "markdown"
}

发送 HTML 格式消息

{
  "action": "send",
  "target": "123456789",
  "message": "<b>加粗文本</b>\n<i>斜体文本</i>\n<code>代码块</code>\n<a href=\"https://example.com\">链接</a>",
  "contentType": "html"
}

回复消息

回复特定消息：

{"action":"send","target":"123456789","message":"这是对您消息的回复","replyTo":"message_id_here"}

发送媒体文件

发送图片

{"action":"send","target":"123456789","media":"https://example.com/image.jpg","caption":"图片描述"}

发送本地文件

{"action":"send","target":"123456789","filePath":"/path/to/local/file.pdf","caption":"文档标题"}

发送 Buffer 数据

{"action":"send","target":"123456789","buffer":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...","caption":"生成的图片"}

消息反应（表情回应）

对消息添加表情反应：

{"action":"send","target":"123456789","messageId":"12345","emoji":"👍"}

支持的常用表情：👍 👎 ❤️ 🔥 🎉 😮 😢 😡

显示输入状态

{"action":"typing","target":"123456789"}

可选状态：typing, upload_photo, record_video, upload_video, record_voice, upload_document, choose_sticker

命令设计

基本命令结构

Telegram Bot 命令以 / 开头，例如 /start, /help, /settings。

命令注册

向 @BotFather 注册命令列表：

/user_info - 获取用户信息
/weather - 查询天气
/remind - 设置提醒
/settings - 个人设置
/help - 帮助信息

命令处理流程

OpenClaw 会自动解析命令并触发相应处理：

1. 用户发送 /weather 北京
2. OpenClaw 解析：{ "command": "weather", "args": ["北京"], ... }
3. Claude 执行天气查询
4. 返回结果给用户

实现命令处理

示例 1：/start 命令

# Claude 处理逻辑
# 当收到消息 "/start" 时：
# 1. 解析用户信息
# 2. 检查是否新用户
# 3. 发送欢迎消息
message action: send
{"target":"用户 ID","message":"欢迎使用 Bot！\n\n使用 /help 查看可用命令。"}

示例 2：带参数的命令

# 用户发送：/remind 30m 喝水
# Claude 解析:
time = args[0] # "30m"
content = args.slice(1).join(' ') # "喝水"
setReminder(time, content, userId)
# 发送确认
{"action":"send","target": userId,"message": f"✅ 提醒已设置！\n⏰ 时间：30 分钟后\n📝 内容：{content}"}

示例 3：交互式命令

使用内联键盘实现交互：

{
  "action": "send",
  "target": "123456789",
  "message": "请选择语言：",
  "replyMarkup": {
    "inline_keyboard": [
      [{"text": "中文", "callback_data": "lang_zh"}, {"text": "English", "callback_data": "lang_en"}],
      [{"text": "日本語", "callback_data": "lang_ja"}]
    ]
  }
}

处理回调查询：

{"action":"callback_query","callbackQueryId":"query_id_here","text":"已选择中文","showAlert":false}

自定义键盘

发送自定义键盘：

{
  "action": "send",
  "target": "123456789",
  "message": "请选择操作：",
  "replyMarkup": {
    "keyboard": [["📊 查询数据", "📝 提交报告"], ["⚙️ 设置", "❓ 帮助"]],
    "resize_keyboard": true,
    "one_time_keyboard": false
  }
}

高级功能

群组管理

加入群组

• 方法 1：邀请链接（Bot 管理员发送邀请链接给 Bot）
• 方法 2：通过用户名（在群组中添加 @YourBotUsername）

群组权限设置

{
  "can_send_messages": true,
  "can_send_media_messages": true,
  "can_send_polls": true,
  "can_delete_messages": true,
  "can_invite_users": true,
  "can_restrict_members": false,
  "can_pin_messages": true,
  "can_promote_members": false
}

获取群组成员

{"action":"getChatMember","target":"group_id_or_username","userId":"123456789"}

内联查询

允许用户在任何聊天中通过 @BotUsername query 调用 Bot：

{
  "action": "inline_query",
  "queryId": "inline_query_id",
  "results": [
    {
      "type": "article",
      "id": "1",
      "title": "结果标题",
      "description": "结果描述",
      "inputMessageContent": {"messageText": "这是发送的消息内容"}
    }
  ]
}

发送投票

{
  "action": "send",
  "target": "123456789",
  "pollQuestion": "你最喜欢哪种编程语言？",
  "pollOption": ["Python", "JavaScript", "Go", "Rust"],
  "pollMulti": false,
  "pollDurationHours": 24
}

消息编辑

编辑已发送的消息：

{"action":"edit","target":"123456789","messageId":"message_id_here","message":"更新后的消息内容"}

删除消息

{"action":"delete","target":"123456789","messageId":"message_id_here"}

引用消息回复

在群组中引用特定用户的消息：

{"action":"send","target":"group_id","message":"回复内容","replyTo":"original_message_id"}

实战案例

案例 1：智能客服 Bot

• 功能清单：自动回复常见问题、工单创建和查询、知识库搜索、人工客服转接
• 实现要点：
  1. 命令设计：/ticket <description> 创建工单，/status <ticket_id> 查询状态，/faq <keyword> 搜索常见问题
  2. 消息处理流程：用户消息 → Claude 分析意图 → 执行相应操作 → 返回结果
  3. 多语言支持：检测用户语言 → 选择对应回复模板

案例 2：任务管理 Bot

• 功能清单：任务创建和管理、定时提醒、进度跟踪、团队协作
• 核心命令：
  • /task add <task_name> - 添加任务
  • /task list - 查看任务列表
  • /task done <id> - 标记完成
  • /remind <time> <task> - 设置提醒
• 数据持久化：使用 OpenClaw 的文件系统或数据库集成，任务数据存储在 ~/.openclaw/data/tasks.json，提醒使用 cron 定时任务

案例 3：内容订阅 Bot

• 功能清单：RSS/Atom 订阅、关键词通知、内容摘要、定时推送
• 实现要点：
  1. 订阅管理：/subscribe <url> 订阅源，/unsubscribe <id> 取消订阅，/list 订阅列表
  2. 定时检查：使用 OpenClaw heartbeat 或 cron 定期检查更新
  3. 推送优化：合并多条更新、添加摘要、媒体预览

最佳实践

1. 消息格式优化

// ✅ 好的做法：使用格式化提升可读性
{
  "message": "*标题*\n\n📝 **内容**：这是正文\n⏰ **时间**：2024-01-01\n\n[查看详情](https://example.com)",
  "contentType": "markdown"
}
// ❌ 避免：纯文本无格式
{
  "message": "标题\n内容：这是正文\n时间：2024-01-01\n查看详情：https://example.com"
}

2. 错误处理

始终处理可能的错误，提供用户友好的反馈：

try:
    result = await sendMessage(target, message)
except error:
    logError(error)
    sendMessage(target, "抱歉，操作失败。请稍后重试或联系支持。")

3. 速率限制

Telegram API 有速率限制，合理控制发送频率：

• 每秒最多 30 条消息
• 每分钟最多 20 条消息到同一群组

使用队列管理发送：

messageQueue = []
async def processQueue():
    while len(messageQueue) > 0:
        msg = messageQueue.pop(0)
        await sendTelegramMessage(msg)
        await sleep(100)  # 控制频率

4. 安全考虑

验证消息来源，防止重放攻击：

# 验证消息来源
async def verifyWebhook(update):
    if update.message.from.id not in allowedUsers:
        return False
    messageTime = update.message.date * 1000
    now = Date.now()
    if now - messageTime > 60000:  # 60 秒有效期
        return False
    return True

# 敏感操作需要确认
async def sensitiveAction(userId, action):
    sendMessage(userId, "⚠️ 确认执行此操作？", {
        "replyMarkup": {
            "inline_keyboard": [
                [{"text": "✅ 确认", "callback_data": f"confirm_{action}"}, {"text": "❌ 取消", "callback_data": "cancel"}]
            ]
        }
    })

5. 日志记录

记录关键操作以便排查问题：

log = {
    "user": update.message.from.id,
    "action": "send_message",
    "timestamp": Date.now(),
    "details": {
        "target": targetId,
        "messageType": "text",
        "length": len(message)
    }
}
appendLog(log)

6. 性能优化

使用并发处理多个独立操作：

async def broadcastMessages(userIds, message):
    promises = [sendMessage(userId, message) for userId in userIds]
    results = await Promise.allSettled(promises)
    for result, index in zip(results, range(len(userIds))):
        if result.status == 'rejected':
            logError(f"Failed to send to {userIds[index]}", result.reason)

调试技巧

查看 Webhook 状态

通过 Claude 询问："检查 Telegram Bot 的 Webhook 状态"。Claude 会调用 {"action":"getWebhookInfo"}。

测试命令

直接向 Bot 发送命令：

• /start - 测试启动命令
• /help - 查看帮助
• /ping - 测试响应
• 在群组中测试 @YourBotUsername hello - 测试内联查询

日志调试

# 查看 OpenClaw Gateway 日志
openclaw gateway logs
# 查看 Telegram 集成日志
tail -f ~/.openclaw/logs/telegram.log

故障排除

问题 1：Bot 无响应

检查清单：

1. Gateway 服务是否运行：openclaw gateway status
2. Webhook 是否配置正确
3. Bot Token 是否有效
4. 网络连接是否正常

问题 2：消息发送失败

常见原因：

• 用户未启动 Bot（需先发送 /start）
• 被用户封禁
• 消息内容违规
• 速率限制

问题 3：Webhook 错误

调试步骤：

# 删除并重新设置 Webhook
# 通过 Claude 执行'重置 Telegram Bot Webhook'
# Claude 会执行
{"action":"deleteWebhook"} // 然后重新设置
{"action":"setWebhook", "url":"https://new-webhook-url"}

总结

通过 OpenClaw 的 message 工具，你可以轻松构建功能强大的 Telegram Bot：

• 简单集成：无需编写代码，通过自然语言与 Claude 交互即可
• 丰富功能：支持消息、媒体、命令、内联查询等全功能
• 灵活扩展：可与 OpenClaw 其他能力（文件、网络、自动化）结合
• 安全可靠：内置错误处理和日志记录

开始构建你的第一个 Telegram Bot 吧！