OpenClaw 与 Telegram 机器人集成指南

配置 Webhook

为了让 Telegram 主动推送用户消息，我们需要配置 Webhook。这允许 Telegram 服务器实时将数据推送到你的 OpenClaw 服务器。

启动 Gateway

确保 OpenClaw Gateway 服务正在运行。如果未启动，可以使用以下命令：

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

注册 Webhook

Webhook URL 通常遵循 https://your-domain.com/api/telegram/webhook 的格式。OpenClaw 会自动处理大部分注册工作，但如果需要手动配置，可以调用：

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

为了安全起见，建议设置 Secret Token 并限制更新类型：

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

测试时，用户在 Telegram 发送消息给 Bot，Telegram 会推送 POST 请求到 Webhook URL，OpenClaw 接收并处理后，Claude 就能在消息历史中看到内容了。

消息处理

当用户发送消息时，OpenClaw 会自动接收并通过消息流呈现给 Claude。理解消息结构有助于更好地解析数据。

消息结构示例

收到的一条典型消息可能长这样：

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

发送消息

使用 message 工具发送文本非常简单。比如回复一条欢迎语：

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

如果需要格式化输出，支持 Markdown 或 HTML。Markdown 示例如下：

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

对于文件传输，无论是远程 URL 还是本地路径，都可以直接指定：

// 发送图片
{"action":"send","target":"123456789","media":"https://example.com/image.jpg","caption":"图片描述"}
// 发送本地文件
{"action":"send","target":"123456789","filePath":"/path/to/local/file.pdf","caption":"文档标题"}

此外，还可以对消息添加表情反应，或者显示输入状态以提升交互体验：

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

命令设计

Telegram Bot 的命令以 / 开头，如 /start, /help。OpenClaw 会自动解析这些命令并触发相应逻辑。

注册命令

向 @BotFather 注册命令列表可以让客户端显示快捷菜单。例如：

• user_info - 获取用户信息
• weather - 查询天气
• remind - 设置提醒

处理流程

当用户发送 /weather 北京 时，OpenClaw 会解析出命令名和参数，传递给 Claude 执行。Claude 返回结果后，再通过 message 工具发回给用户。

交互式界面

除了普通文本，我们还可以使用内联键盘实现更丰富的交互。例如让用户选择语言：

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

处理回调查询时，只需调用对应的回调动作即可。

高级功能

群组管理

Bot 可以加入群组并管理权限。例如设置成员是否可以发送消息或邀请新用户：

{
  "can_send_messages": true,
  "can_send_media_messages": true,
  "can_delete_messages": true,
  "can_restrict_members": false
}

内联查询与投票

允许用户在任何聊天中通过 @BotUsername query 调用 Bot，或者发起投票。投票示例：

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

消息编辑与删除

已发送的消息支持编辑或删除，这在动态更新通知时非常有用：

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

实战场景

智能客服 Bot

结合知识库搜索和工单系统，可以实现自动回复常见问题，并在复杂情况下转接人工。关键是通过命令设计区分意图，例如 /ticket <description> 创建工单。

任务管理 Bot

利用定时任务和数据库持久化，可以管理个人任务。核心命令包括 /task add 添加任务，/remind 设置提醒。数据存储在 ~/.openclaw/data/tasks.json 中。

内容订阅 Bot

通过 RSS/Atom 订阅源，配合关键词过滤和摘要生成，定期推送最新资讯。注意优化推送频率，避免打扰用户。

最佳实践

消息格式优化

使用 Markdown 提升可读性，避免纯文本堆砌。例如用 Emoji 和加粗突出重点。

错误处理

始终捕获异常并返回友好的提示。不要直接把后端错误抛给用户：

try {
  const result = await sendMessage(target, message);
} catch (error) {
  logError(error);
  sendMessage(target, "抱歉，操作失败。请稍后重试。");
}

速率限制

Telegram API 有严格的频率限制。每秒最多 30 条消息，同一群组每分钟 20 条。建议使用队列管理发送，控制间隔：

const processQueue = async () => {
  while (messageQueue.length > 0) {
    const msg = messageQueue.shift();
    await sendTelegramMessage(msg);
    await sleep(100); // 控制频率
  }
};

安全与日志

验证 Webhook 来源和时间戳，防止重放攻击。敏感操作需二次确认。同时记录关键操作日志，便于排查问题。

调试与故障排除

查看 Webhook 状态可以通过询问 Claude 完成，它会调用 getWebhookInfo。如果 Bot 无响应，检查 Gateway 是否运行、Token 是否有效以及网络连通性。消息发送失败通常是因为用户未启动 Bot 或被封禁。Webhook 错误可以尝试重置 Webhook 重新注册。

总结

通过 OpenClaw 的 message 工具，你可以轻松构建功能强大的 Telegram Bot。它支持简单集成、丰富功能、灵活扩展以及安全可靠的内建机制。无论是智能客服还是任务管理，都能快速落地。