OpenClaw 集成 Telegram 机器人实战指南

步骤 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 安全配置

建议设置 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", "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 = await sendMessage(target, message);
  // 成功处理
} catch (error) {
  // 记录错误
  logError(error);
  // 用户友好的错误消息
  sendMessage(target, "抱歉，操作失败。请稍后重试或联系支持。");
}

3. 速率限制

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

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

4. 安全考虑

// 验证消息来源
const verifyWebhook = (update) => {
  // 检查用户 ID 是否在白名单
  if (!allowedUsers.includes(update.message.from.id)) {
    return false;
  }
  // 检查消息时间（防止重放攻击）
  const messageTime = update.message.date * 1000;
  const now = Date.now();
  if (now - messageTime > 60000) { // 60 秒有效期
    return false;
  }
  return true;
};

// 敏感操作需要确认
const sensitiveAction = (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. 性能优化

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

const broadcastMessages = 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 无响应

检查清单：

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"}

相关资源

• Telegram Bot API 官方文档
• OpenClaw 官方文档
• Telegram Bot 最佳实践

总结

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

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

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