首页/@claw-academy

"配置 Telegram Provider"

龙虾学堂
龙虾学堂2026年5月7日

"详解 OpenClaw 中 Telegram Provider 的配置字段，以及如何测试和验证配置是否生效"

配置 Telegram Provider

本文聚焦：Telegram Provider 配置字段详解 + 配置验证与测试方法

前置知识：创建 Telegram Bot 下一篇：创建飞书机器人

前置条件

在开始配置之前，请确保：

知识点 1：Telegram Provider 配置字段详解

什么是 Provider

在 OpenClaw 中，Provider 是连接外部消息平台的适配器。Telegram Provider 负责让 OpenClaw 与你的 Telegram Bot 通信，实现消息收发功能。

配置位置与结构

Telegram Provider 的配置位于 openclaw.json 文件的 channels 数组中。配置文件通常位于：

  • Linux/macOS: ~/.openclaw/openclaw.json
  • Windows: %USERPROFILE%\.openclaw\openclaw.json

基本配置结构：

{
  "channels": [
    {
      "id": "telegram",
      "type": "telegram",
      "token": "YOUR_BOT_TOKEN",
      "default": "YOUR_CHAT_ID"
    }
  ]
}

核心字段说明

id - 频道标识符

  • 类型：字符串
  • 作用：在 OpenClaw 内部唯一标识这个频道
  • 建议：使用 "telegram" 或 "tg-main" 等简洁名称
  • 注意：同一个 openclaw.json 中不能有重复的 id

type - 频道类型

  • 类型：字符串
  • 固定值："telegram"
  • 作用：告诉 OpenClaw 使用 Telegram Provider 处理这个频道

token - Bot Token（必填）

  • 类型：字符串
  • 来源：从 @BotFather 获取（见前置文章）
  • 格式：123456789:ABCdefGHIjklMNOpqrSTUvwxyz
  • 安全提示：
    • 不要将 token 提交到 Git 仓库
    • 使用 .gitignore 忽略配置文件
    • 生产环境建议使用环境变量注入

default - 默认聊天 ID（可选但推荐）

  • 类型：字符串或数字
  • 作用：指定默认的消息接收方
  • 格式：
    • 个人聊天：纯数字，如 "123456789"
    • 群组：以 - 开头的数字，如 "-1001234567890"
  • 获取方法：
    1. 给 Bot 发送任意消息
    2. 访问 https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
    3. 在返回的 JSON 中找到 "chat":{"id":123456789 字段

完整配置示例

{
  "channels": [
    {
      "id": "telegram",
      "type": "telegram",
      "token": "123456789:ABCdefGHIjklMNOpqrSTUvwxyz",
      "default": "123456789"
    }
  ],
  "agents": [
    {
      "id": "my-agent",
      "channels": ["telegram"]
    }
  ]
}

常见陷阱

陷阱现象解决方案
Token 包含多余空格Gateway 启动报错检查并删除 token 前后的空格
Chat ID 格式错误消息发送失败确保是纯数字，不带引号外的字符
未设置 default需要每次指定 target添加 default 简化调用
群组 Chat ID 格式错误无法发送到群组使用 -100 开头的完整 ID

知识点 2：配置验证与测试方法

验证步骤 1：配置文件语法检查

在启动 Gateway 之前，先验证 JSON 语法：

# 使用 Python 验证
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null && echo "JSON 格式正确"

# 或使用 jq（如已安装）
jq . ~/.openclaw/openclaw.json > /dev/null && echo "JSON 格式正确"

验证步骤 2：Gateway 启动检查

配置完成后，验证 Gateway 能否正常启动：

# 前台启动（便于查看日志）
openclaw gateway

# 或使用 Docker
docker-compose up

成功标志：

  • 控制台显示 Gateway 启动信息
  • 没有关于 Telegram Provider 的错误日志
  • 看到 Telegram webhook 设置成功的信息

验证步骤 3：消息接收测试

Telegram Provider 使用 webhook 接收消息。测试步骤：

# 1. 给 Bot 发送一条测试消息
# 在 Telegram 中打开你的 Bot，发送 "Hello"

# 2. 检查 Gateway 日志
# 应该能看到收到消息的日志输出，例如：
# [Telegram] Received message from 123456789: Hello

常见问题：如果收不到消息，检查：

  • Gateway 是否有公网可访问的 URL（Telegram webhook 需要）
  • 防火墙是否允许 Telegram 服务器的 IP 访问

验证步骤 4：消息发送测试

使用 message 工具向 Telegram 发送测试消息：

{
  "action": "send",
  "channel": "telegram",
  "message": "🎉 OpenClaw 配置成功！"
}

预期结果：Telegram 收到消息，显示 "🎉 OpenClaw 配置成功！"

验证步骤 5：双向通信测试

测试 Agent 能否接收和回复消息：

  1. 在 Telegram 中向 Bot 发送消息
  2. 检查 Agent 是否收到（查看 Gateway 日志）
  3. 让 Agent 回复一条消息
  4. 确认 Telegram 收到回复

故障排查速查表

问题排查步骤
Gateway 启动失败检查 JSON 语法、token 格式、配置文件路径
收不到消息检查 webhook URL 设置、防火墙、公网访问
发不出消息检查 token 权限、chat ID 正确性、网络连接
消息延迟检查网络连接、Telegram API 状态
Bot 无响应检查 Bot 是否被 @BotFather 停用

实践建议

  1. 使用环境变量保护 Token

    {
  "token": "${TELEGRAM_BOT_TOKEN}"
}

    在启动时注入：TELEGRAM_BOT_TOKEN=xxx openclaw gateway

  2. 为不同环境配置不同频道

    • 开发环境："telegram-dev"
    • 生产环境："telegram-prod"

  3. 发送消息到指定聊天 如果需要发送到多个聊天，可以在调用时指定 target：

    {"action": "send", "channel": "telegram", "target": "123456789"}

  4. 定期检查 Bot 权限 确保 Bot 在群组中有发送消息的权限，必要时重新添加到群组

  5. 使用日志调试 遇到问题时，在 openclaw.json 中设置 "logLevel": "debug" 查看详细通信日志

参考资源

相关阅读

#["telegram"#"provider"#"配置"]