OpenClaw
渠道集成10 分钟阅读

OpenClaw Telegram 集成完整指南

学习如何创建 Telegram 机器人并连接到 OpenClaw。完整教程涵盖机器人创建、配置、命令和群聊设置。

O

OpenClaw Guides

Tutorial Authors

概述

Telegram 集成允许您通过专用 Telegram 机器人与 OpenClaw 进行交互。OpenClaw 默认使用 grammY 框架进行长轮询，并可选择在生产部署中使用 webhook 支持。

前提条件

  • 已安装并运行 OpenClaw
  • 一个 Telegram 账户

步骤1：创建 Telegram 机器人

与 BotFather 对话

  1. 打开 Telegram 搜索 @BotFather
  2. 开始对话并发送 /newbot
  3. 按照提示操作：
You: /newbot

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

You: My OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example:
           TetrisBot or tetris_bot.

You: myopenclaw_bot

BotFather: Done! Congratulations on your new bot. You will find it at
           t.me/myopenclaw_bot. You can now add a description, about
           section and profile picture for your bot.

           Use this token to access the HTTP API:
           123456789:ABCdefGHIjklMNOpqrsTUVwxyz

           Keep your token secure and store it safely.

保存机器人令牌 — 下一步您将需要它。

禁用隐私模式（群组推荐）

如果您计划在群聊中使用机器人，请禁用隐私模式以便机器人可以读取所有消息：

/setprivacy
@myopenclaw_bot
Disable

更改隐私模式后，您必须将机器人从现有群组中移除并重新添加，更改才能生效。或者，将机器人提升为群组管理员 — 管理员机器人始终可以接收所有消息。

步骤2：配置 OpenClaw

令牌存储

您可以通过两种方式存储机器人令牌。配置文件优先于环境变量。

选项 A — 环境变量：

bash
# 添加到 ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

选项 B — 直接写入配置：

json5
// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

最小配置

编辑 ~/.openclaw/openclaw.json：

json5
{
  channels: {
    telegram: {
      // 从环境变量 TELEGRAM_BOT_TOKEN 获取令牌，或直接设置 botToken
    }
  }
}

这就是您需要的全部配置 — 当 Telegram 通道配置完成后，OpenClaw 会自动开始长轮询。

步骤3：测试您的机器人

  1. 打开 Telegram 搜索您的机器人用户名
  2. 用 /start 开始对话
  3. 发送任何消息进行测试

访问控制 — DM 策略

通过 dmPolicy 控制谁可以在私聊中向您的机器人发送消息：

| 策略 | 行为 | |--------|----------| | "pairing"（默认） | 未知发送者会收到一个过期的配对码；您通过 CLI 批准 | | "allowlist" | 只有 allowFrom 中的用户 ID / @用户名可以发送消息 | | "open" | 任何人都可以向机器人发送消息 | | "disabled" | 完全关闭私聊功能 |

配对模式（默认）

当新用户向机器人发送消息时，他们会收到一个配对码。通过以下方式批准：

bash
# 列出待处理的配对请求
openclaw pairing list telegram

# 批准特定的配对码
openclaw pairing approve telegram <CODE>

配对码在 1 小时后过期。

白名单模式

json5
{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

开放模式

json5
{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

群聊支持

启用群组访问

将群组 ID 添加到 groups 对象中。使用 "*" 允许所有群组：

json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // 使用默认设置的特定群组
        "-1009876543210": {             // 使用自定义设置的特定群组
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

或允许所有群组：

json5
{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

群组策略

控制谁可以在群组中与机器人交互：

| 设置 | 描述 | |---------|-------------| | groupPolicy: "open" | 任何群组成员都可以向机器人发送消息 | | groupPolicy: "allowlist" | 只有 groupAllowFrom 中的发送者可以交互 | | groupPolicy: "disabled" | 机器人忽略所有群组消息 |

json5
{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

提及要求

默认情况下，机器人在群组中需要 @提及。您可以按群组更改此设置：

json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // 机器人回复所有消息
        }
      }
    }
  }
}

或者在群聊中使用仅限当前会话的命令 /activation always。

按群组自定义覆盖

每个群组条目支持以下字段：

| 字段 | 描述 | |-------|-------------| | groupPolicy | 覆盖全局群组策略 | | requireMention | 是否需要 @提及 | | skills | 此群组中可用的技能 | | allowFrom | 此群组的发送者白名单 | | systemPrompt | 此群组的自定义系统提示词 | | enabled | 启用/禁用此特定群组 |

消息格式与分块

HTML 解析模式

OpenClaw 使用 Telegram 的 HTML 解析模式发送消息（非 Markdown）。LLM 输出的 Markdown 会自动转换为 HTML 安全标签。如果 Telegram 拒绝 HTML，消息将以纯文本形式重新发送。

文本分块

长消息会被拆分为多条 Telegram 消息：

json5
{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // 每条消息最大字符数（默认：4000）
      chunkMode: "newline"     // "length"（默认）或 "newline"
    }
  }
}
  • "length" — 在字符限制处拆分
  • "newline" — 在应用长度限制之前在段落边界处拆分

媒体处理

媒体大小限制

json5
{
  channels: {
    telegram: {
      mediaMaxMb: 5    // 最大文件大小，单位 MB（默认：5）
    }
  }
}

贴纸

  • 静态贴纸（WEBP）通过视觉处理并描述给 LLM
  • 动画/视频贴纸 会被跳过
  • 贴纸描述缓存在 ~/.openclaw/telegram/sticker-cache.json 中，以避免重复的视觉调用

要启用机器人发送贴纸：

json5
{
  channels: {
    telegram: {
      actions: {
        sticker: true    // 默认：false
      }
    }
  }
}

历史记录与上下文

json5
{
  channels: {
    telegram: {
      historyLimit: 50,        // 群组上下文（默认：50）
      dmHistoryLimit: 100      // 私聊上下文
    }
  }
}

按用户私聊覆盖：

json5
{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

设置为 0 以禁用历史记录。

流式传输

OpenClaw 在私聊中支持基于草稿的流式传输（需要启用论坛主题）：

| 设置 | 描述 | |---------|-------------| | streamMode: "off" | 禁用流式传输（默认） | | streamMode: "partial" | 持续更新草稿消息 | | streamMode: "block" | 分块更新草稿消息 |

分块模式设置：

json5
{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

Webhook 模式（生产环境）

对于生产部署，使用 webhook 替代长轮询：

json5
{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // 本地路径，默认：/telegram-webhook
    }
  }
}

Webhook 监听器绑定到 0.0.0.0:8787。当设置了 webhookUrl 时，OpenClaw 会自动从轮询模式切换到 webhook 模式。

命令

原生命令

OpenClaw 在启动时会向 Telegram 的机器人菜单注册以下命令：

| 命令 | 描述 | |---------|-------------| | /start | 欢迎消息 | | /status | 显示机器人状态 | | /reset | 重置对话 | | /model | 显示/切换模型 |

自定义命令

通过配置添加菜单项（仅菜单显示 — 除非在其他地方处理，否则不会执行）：

json5
{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

命令名称必须为小写 a-z0-9_，1-32 个字符。前导 / 会自动去除。不能覆盖原生命令。

内联按钮

控制内联按钮的可用性：

| 设置 | 作用范围 | |---------|-------| | capabilities.inlineButtons: "off" | 禁用 | | capabilities.inlineButtons: "dm" | 仅私聊 | | capabilities.inlineButtons: "group" | 仅群组 | | capabilities.inlineButtons: "all" | 私聊和群组 | | capabilities.inlineButtons: "allowlist" | 两者皆可 + 发送者过滤（默认） |

网络与代理

json5
{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // Bot API 请求超时（默认：500）
      network: {
        autoSelectFamily: false   // 禁用 Happy Eyeballs（Node 22 默认开启）
      },
      proxy: "socks5://127.0.0.1:1080"   // Bot API 的 SOCKS/HTTP 代理
    }
  }
}

故障排除

机器人不响应

  1. 验证令牌是否正确：
bash
curl "https://api.telegram.org/bot<TOKEN>/getMe"
  1. 检查 OpenClaw 日志：
bash
openclaw logs --follow

消息未到达群组

  • 隐私模式必须已禁用（/setprivacy → Disable）或机器人必须是管理员
  • 使用 /activation always 测试（仅限当前会话）；通过配置中的 requireMention: false 持久化

IPv6 路由失败

如果 IPv6 路由失败，机器人可能会静默停止响应。检查 api.telegram.org 的 DNS：

bash
dig api.telegram.org AAAA

通过启用 IPv6 出站或强制使用 IPv4 来修复：

bash
# 添加到 /etc/hosts
149.154.167.220  api.telegram.org

或使用网络配置：

json5
{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

长轮询中止（Node 22+）

Node 22 对 AbortSignal 实例更加严格。升级 OpenClaw 到最新版本或降级到 Node 20。

setMyCommands 失败

到 api.telegram.org 的出站 HTTPS/DNS 可能被阻止。检查您的防火墙规则。

安全最佳实践

  1. 永远不要分享您的机器人令牌 — 如果泄露，立即通过 BotFather 撤销
  2. 使用配对或白名单 进行私聊访问控制
  3. 设置群组策略 以控制谁可以在群组中交互
  4. 安全地查找用户 ID 通过 openclaw logs --follow 或 Bot API 的 getUpdates 端点 — 避免使用第三方 ID 机器人
  5. 在生产部署中使用带密钥的 webhook

后续步骤