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

{
  "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 吧！🚀