15-OpenClaw与Telegram机器人集成

Ne0inhk

22 Mar 2026 — 10 min read

OpenClaw 与 Telegram 机器人集成

✦ 免费专栏｜全套教程： OpenClaw 从入门到精通
✦ 开篇总览｜最新目录：最新 OpenClaw 教程｜从入门到精通｜AI 智能助手 / 自动化 / Skills 实战（原 Clawdbot/Moltbot）

概述

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

前置准备

环境要求

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

核心概念

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

message 工具支持的主要操作： ├── send - 发送消息、媒体、文件 ├── broadcast - 批量发送消息 ├── reactions - 消息反应（表情回应） ├── typing - 显示输入状态 └── channels - 频道和群组管理

Bot 创建

步骤 1：在 Telegram 创建 Bot

打开 Telegram，搜索 @BotFather

保存 Token

Token 格式: <bot_id>:<token_string> 示例: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

创建新 Bot

用户发送: /newbot BotFather 回复: 输入 Bot 名称 用户发送: MyAwesomeBot BotFather 回复: 输入 Bot 用户名（必须以 bot 结尾） 用户发送: MyAwesome_bot BotFather 返回: ✅ Bot 创建成功！ Token: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

步骤 2：配置 OpenClaw

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

// ~/.openclaw/config.json{"channels":{"telegram":{"enabled":true,"bots":{"default":{"token":"1234567890:ABCdefGHIjklMNOpqrsTUVwxyz","name":"MyAwesomeBot"}}}}}

步骤 3：验证 Bot 状态

使用 OpenClaw 检查 Bot 连接状态：

询问 Claude: "检查 Telegram Bot 的连接状态"

Claude 会通过 message 工具查询 Bot 信息：

{"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 安全配置

{"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","username":"username","language_code":"en"},"chat":{"id":123456789,"first_name":"User","username":"username","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 注册命令列表：

发送给 BotFather: /setcommands 回复: user_info - 获取用户信息 weather - 查询天气 remind - 设置提醒 settings - 个人设置 help - 帮助信息

命令处理流程

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

用户发送: /weather 北京 ↓ OpenClaw 解析: { "command": "weather", "args": ["北京"], "from": {用户信息}, "chat": {聊天信息} } ↓ Claude 执行天气查询 ↓ 返回结果给用户

实现命令处理

示例 1：/start 命令

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

示例 2：带参数的命令

// 用户发送: /remind 30m 喝水// Claude 解析:const time = args[0];// "30m"const content = args.slice(1).join(' ');// "喝水"// 设置定时提醒setReminder(time, content, userId);// 发送确认{"action":"send","target": userId,"message":`✅ 提醒已设置！\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{const result =awaitsendMessage(target, message);// 成功处理}catch(error){// 记录错误logError(error);// 用户友好的错误消息sendMessage(target,"抱歉，操作失败。请稍后重试或联系支持。");}

3. 速率限制

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

// 避免短时间内大量发送// 每秒最多 30 条消息// 每分钟最多 20 条消息到同一群组// 使用队列管理发送const messageQueue =[];constprocessQueue=async()=>{while(messageQueue.length >0){const msg = messageQueue.shift();awaitsendTelegramMessage(msg);awaitsleep(100);// 控制频率}};

4. 安全考虑

// 验证消息来源constverifyWebhook=(update)=>{// 检查用户 ID 是否在白名单if(!allowedUsers.includes(update.message.from.id)){returnfalse;}// 检查消息时间（防止重放攻击）const messageTime = update.message.date *1000;const now = Date.now();if(now - messageTime >60000){// 60秒有效期returnfalse;}returntrue;};// 敏感操作需要确认constsensitiveAction=(userId, action)=>{// 发送确认请求sendMessage(userId,"⚠️ 确认执行此操作？",{replyMarkup:{inline_keyboard:[[{text:"✅ 确认",callback_data:`confirm_${action}`},{text:"❌ 取消",callback_data:"cancel"}]]}});};

5. 日志记录

// 记录关键操作const log ={user: update.message.from.id,action:"send_message",timestamp: Date.now(),details:{target: targetId,messageType:"text",length: message.length }};// 存储日志appendLog(log);

6. 性能优化

// 使用并发处理多个独立操作constbroadcastMessages=async(userIds, message)=>{const promises = userIds.map(userId=>sendMessage(userId, message));// 限制并发数const results =await Promise.allSettled(promises);// 处理失败 results.forEach((result, index)=>{if(result.status ==='rejected'){logError(`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 无响应

检查清单：

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

问题 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 吧！🚀