Telegram - Bot 接入指南

Telegram 是全球广受欢迎的即时通讯平台，通过其 Bot API（机器人接口）可以轻松接入 OpenClaw，实现自动化对话和群组交互。

前置要求

• 一个 Telegram 账号
• OpenClaw Gateway（网关）已安装并运行

创建 Bot

第一步：通过 @BotFather 创建机器人

在 Telegram 中搜索 @BotFather 并发送 /newbot，按照提示输入 Bot 显示名称和用户名（必须以 bot 结尾）。创建成功后会返回 Bot Token（机器人令牌），格式如 123456789:ABCdefGHIjklMNOpqrsTUVwxyz。

安全提示

Bot Token 是访问你机器人的唯一凭证，请妥善保管，不要泄露到公开仓库或日志中。

第二步：配置 OpenClaw

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      dmPolicy: "pairing",      // DM Policy（私信策略）
      groups: {
        "*": {                   // 匹配所有群组
          requireMention: true   // 需要 @机器人 才响应
        }
      }
    }
  }
}

也可以通过 Environment Variable（环境变量）设置：export TELEGRAM_BOT_TOKEN="123:abc"

第三步：重启 Gateway

openclaw gateway restart

Polling vs Webhook 模式

Polling（轮询模式）— 默认

Gateway 主动拉取新消息，适合开发测试和无公网 IP 的环境，无需额外配置。

Webhook（回调模式）

Telegram 服务器主动推送消息，适合生产环境，响应更快：

{
  channels: {
    telegram: {
      mode: "webhook",
      webhookUrl: "https://your-domain.com/api/channels/telegram/webhook",
      webhookSecret: "your-random-secret-string"
    }
  }
}

Webhook 要求

必须使用 HTTPS，服务器需有公网可访问的域名，建议设置 webhookSecret 验证请求来源。

群组设置

默认 Bot 在群组中只能收到 @提及 的消息。要读取所有消息，在 BotFather 中发送 /setprivacy 选择 Disable，或将 Bot 设为群组管理员。

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false },  // 指定群组 Chat ID
        "*": { requireMention: true }                  // 其他所有群组
      }
    }
  }
}

DM Policy（私信策略）与 Allowlist（白名单）

策略	说明
pairing	用户需先获取 Pairing Code（配对码）验证
allowlist	仅允许指定用户私聊
open	所有人均可私聊（谨慎使用）

allowFrom 使用 Telegram 的数字 User ID（用户ID），可通过 @userinfobot 获取：

{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, 987654321]
    }
  }
}

Proxy（代理）配置

{
  channels: {
    telegram: {
      proxy: {
        type: "socks5",        // 支持 http / socks5
        host: "127.0.0.1",
        port: 1080,
        username: "user",      // 可选
        password: "pass"       // 可选
      }
    }
  }
}

注册 Bot Commands（命令）

通过 BotFather 发送 /setcommands 注册命令菜单：

start - 开始对话
help - 获取帮助
reset - 重置对话上下文
status - 查看机器人状态

常见问题

Bot 在群组中不回复

1. 检查 Privacy Mode（隐私模式）是否已禁用，或 Bot 是否为管理员
2. 确认 groups 配置包含该群组的 Chat ID 或使用了 * 通配符
3. 查看 Gateway 日志确认消息是否被接收

Token 无效错误

重新从 BotFather 获取 Token，确保复制完整（包含冒号前的数字部分）。

🇨🇳 中国用户须知

Telegram 在中国大陆无法直接访问，服务器端和客户端均需要代理。

服务器端代理：OpenClaw 部署在中国境内的服务器上，务必配置 channels.telegram.proxy，否则 Gateway 无法连接 Telegram API。

客户端访问：建议在 Telegram 客户端内设置 MTProto Proxy 以获得更稳定的连接。

注册提示：中国大陆 +86 手机号可正常注册，建议注册后立即设置 Two-Factor Authentication（两步验证）。

替代方案：团队成员主要在国内时，建议优先考虑企业微信、钉钉或飞书。