OpenClaw 与 Telegram 机器人集成指南

OpenClaw 与 Telegram 机器人集成指南 | 极客日志

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

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

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

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

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

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

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

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

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

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

用户在 Telegram 发送消息给 Bot → Telegram 推送 POST 请求到 Webhook URL → OpenClaw 接收并处理 → Claude 通过消息历史看到用户消息

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

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

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

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

{"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":"文档标题"}

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

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

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

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

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

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

// 用户发送：/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}`
}

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

{"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. 命令设计：
   /ticket <description> - 创建工单
   /status <ticket_id> - 查询工单状态
   /faq <keyword> - 搜索常见问题
2. 消息处理流程：
   用户消息 → Claude 分析意图 → 执行相应操作 → 返回结果
3. 多语言支持：
   检测用户语言 → 选择对应回复模板

## 功能清单
- 任务创建和管理
- 定时提醒
- 进度跟踪
- 团队协作

## 核心命令
/task add <task_name> - 添加任务
/task list - 查看任务列表
/task done <id> - 标记完成
/remind <time> <task> - 设置提醒

## 数据持久化
使用 OpenClaw 的文件系统或数据库集成：
- 任务数据存储在 ~/.openclaw/data/tasks.json
- 提醒使用 cron 定时任务

## 功能清单
- RSS/Atom 订阅
- 关键词通知
- 内容摘要
- 定时推送

## 实现要点
1. 订阅管理：
   /subscribe <url> - 订阅源
   /unsubscribe <id> - 取消订阅
   /list - 订阅列表
2. 定时检查：
   使用 OpenClaw heartbeat 或 cron 定期检查更新
3. 推送优化：
   - 合并多条更新
   - 添加摘要
   - 媒体预览

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

// 始终处理可能的错误
try {
  const result = await sendMessage(target, message);
  // 成功处理
} catch (error) {
  // 记录错误
  logError(error);
  // 用户友好的错误消息
  sendMessage(target, "抱歉，操作失败。请稍后重试或联系支持。");
}

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

// 验证消息来源
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" }]
      ]
    }
  });
};

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

// 使用并发处理多个独立操作
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);
    }
  });
};

# 通过 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

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

OpenClaw 与 Telegram 机器人集成指南

OpenClaw 与 Telegram 机器人集成

概述

前置准备

环境要求

核心概念

Bot 创建

步骤 1：在 Telegram 创建 Bot

步骤 2：配置 OpenClaw

步骤 3：验证 Bot 状态

Webhook 配置

为什么需要 Webhook？

步骤 1：准备 Webhook 服务器

步骤 2：配置 Webhook URL

步骤 3：注册 Webhook

步骤 4：验证 Webhook

Webhook 安全配置

消息处理

接收消息

消息结构示例

发送文本消息

发送 Markdown 格式消息

发送 HTML 格式消息

回复消息

发送媒体文件

发送图片

发送本地文件

发送 Buffer 数据

消息反应（表情回应）

显示输入状态

命令设计

基本命令结构

命令注册

命令处理流程

实现命令处理

示例 1：/start 命令

示例 2：带参数的命令

示例 3：交互式命令

自定义键盘

高级功能

群组管理

加入群组

群组权限设置

获取群组成员

内联查询

发送投票

消息编辑

删除消息

引用消息回复

实战案例

案例 1：智能客服 Bot

案例 2：任务管理 Bot

案例 3：内容订阅 Bot

最佳实践

1. 消息格式优化

2. 错误处理

3. 速率限制

4. 安全考虑

5. 日志记录

6. 性能优化

调试技巧

查看 Webhook 状态

测试命令

日志调试

故障排除

问题 1：Bot 无响应

问题 2：消息发送失败

问题 3：Webhook 错误

相关资源

总结

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具