OpenClaw 技能库 | 最大的 OpenClaw 扩展库

状态：已可用于生产环境。通过 grammY 支持机器人私聊与群聊。默认使用 long-polling；也支持 webhook。

Tutorial.step

新手快速配置

1. 用 ''@BotFather'' 创建一个 bot（''直达链接''）。务必确认 handle 就是 ''@BotFather''，然后复制 bot token。

2. 配置 token：

- 环境变量：''TELEGRAM_BOT_TOKEN=...''

- 或配置：''channels.telegram.botToken: "..."''。

- 两者同时设置时，以 config 为准（env 仅作为 default account 兜底）。

3. 启动 Gateway。

4. 私信默认启用 pairing；第一次联系会收到配对码，批准后才会处理消息。

最小配置：

Json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
    },
  },
}

Tutorial.step

它是什么

- 由 Gateway 管理的 Telegram Bot API 通道。

- 确定性路由：回复只会回到 Telegram，不让模型选择通道。

- DM uses agent's main session by default; group chats are isolated as ''agent:<agentId>:telegram:group:<chatId>''.

Tutorial.step

设置（快速路径）

Tutorial.step

1）创建 bot token（BotFather）

1. 打开 Telegram，与 ''@BotFather'' 对话（''直达链接''），确认 handle 就是 ''@BotFather''。

2. 运行 ''/newbot''，按提示完成（name + 以 ''bot'' 结尾的 username）。

3. 复制 token 并妥善保管。

可选设置：

- ''/setjoingroups'' — 允许/禁止将 bot 加入群组

- ''/setprivacy'' — 控制 bot 是否能看到所有群消息

可选设置：

- ''/setjoingroups'' — 允许/禁止将 bot 加入群组

- ''/setprivacy'' — 控制 bot 是否能看到所有群消息

Tutorial.step

2）配置 token（env 或 config）

示例：

Json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

环境变量方式：''TELEGRAM_BOT_TOKEN=...''（仅对 default account 生效）。env 与 config 同时存在时，以 config 为准。

多账号：使用 ''channels.telegram.accounts'' 配置每个账号的 token（可选 ''name''）。共享结构见 ''/gateway/configuration''。

3. 启动 Gateway：当 token 可解析（config 优先，env 兜底）时 Telegram 通道会启动。

4. 私信默认 pairing：首次联系会给出配对码，批准后才会处理消息。

5. 群聊：把 bot 加入群；决定 BotFather privacy/admin 策略（见下）；再用 ''channels.telegram.groups'' 控制 mention gating 与 allowlist。

Tutorial.step

Telegram 侧：Token / 隐私 / 权限

Tutorial.step

Token（BotFather）

- ''/newbot'' 会创建 bot 并返回 token（务必保密）。

- 一旦泄露，在 @BotFather 里撤销/重置 token，并更新你的配置。

Tutorial.step

群消息可见性（Privacy Mode）

Telegram bot 默认启用 Privacy Mode，这会限制它能收到的群消息范围。如果你需要 bot 看见群里的所有消息，有两种方式：

- 用 ''/setprivacy'' 关闭 privacy mode，''或''

- 把 bot 设为群 管理员（管理员 bot 可以收到所有消息）。

注意： 切换 privacy mode 后，需要把 bot 从群里移除再重新加入，设置才会生效。

Tutorial.step

群权限（管理员）

管理员权限在群内 UI 设置。管理员 bot 会收到所有群消息；只有在确实需要"全可见"时再这样做。

Tutorial.step

工作方式（行为）

- 入站消息会被归一化到通用的 channel envelope（包含 reply 上下文与媒体占位符）。

- 群聊默认需要 mention 才回复（原生 @mention 或 ''agents.list[].groupChat.mentionPatterns'' / ''messages.groupChat.mentionPatterns'' 命中）。

- 多 agent 时可在 ''agents.list[].groupChat.mentionPatterns'' 做每个 agent 的覆盖。

- 回复始终回到触发它的 Telegram chat。

- long-polling 使用 grammY runner 并按 chat 做顺序处理；总体并发受 ''agents.defaults.maxConcurrent'' 限制。

- Telegram Bot API 没有已读回执，因此没有 ''sendReadReceipts''。

Tutorial.step

草稿式流式回复（Draft streaming）

OpenClaw 可以在 Telegram 私聊中用 ''sendMessageDraft'' 流式更新部分回复。

要求：

- 在 @BotFather 中为 bot 启用 Threaded Mode（forum topic mode）。

- 仅限私聊线程（Telegram 会在入站消息中包含 ''message_thread_id''）。

- ''channels.telegram.streamMode'' 不为 ''"off"''（默认 ''"partial"''；''"block"'' 会进行分块草稿更新）。

草稿流式仅支持私聊；Telegram 在群/频道里不支持该机制。

Tutorial.step

格式化（Telegram HTML）

- 出站 Telegram 文本使用 ''parse_mode: "HTML"''（Telegram 支持的标签子集）。

- Markdown-ish 输入会渲染为 Telegram 安全的 HTML（加粗/斜体/删除线/代码/链接）；块级元素会被扁平化为带换行/项目符号的文本。

- 来自模型的原始 HTML 会被转义，避免 Telegram parse 错误。

- 如果 Telegram 拒绝 HTML payload，OpenClaw 会用纯文本重试同一条消息。

Tutorial.step

命令（原生 + 自定义）

OpenClaw 会在启动时向 Telegram 的 bot 菜单注册原生命令（如 ''/status''、''/reset''、''/model''）。

你也可以通过配置把自定义命令加到菜单里：

说明：

- 自定义命令只是菜单入口；除非你在别处处理，否则 OpenClaw 不会自动实现它们。

- 命令名会被规范化（去掉前导 ''/''、转小写），只能包含 ''a-z''、''0-9''、''_''（长度 1–32）。

- 自定义命令不能覆盖原生命令；冲突项会被忽略并记录日志。

- 如果禁用 ''commands.native''，则只注册自定义命令（或在没有自定义命令时清空菜单）。

Tutorial.step

排障

- 日志中出现 ''setMyCommands failed'' 通常意味着到 ''api.telegram.org'' 的 HTTPS/DNS 出站被阻断。

- 看到 ''sendMessage'' 或 ''sendChatAction'' 失败时，优先检查 IPv6 路由与 DNS。

更多：''/channels/troubleshooting''。

Tutorial.step

限制

- 出站文本按 ''channels.telegram.textChunkLimit'' 分段（默认 4000）。

- 可选按空行优先分段：''channels.telegram.chunkMode="newline"''（段落边界）后再按长度分段。

- 媒体下载/上传上限：''channels.telegram.mediaMaxMb''（默认 5MB）。

- Telegram Bot API 请求超时：''channels.telegram.timeoutSeconds''（默认 500，grammY）。建议设置更小以避免长时间挂起。

- 群历史上下文：''channels.telegram.historyLimit''（或 ''channels.telegram.accounts.*.historyLimit''），兜底为 ''messages.groupChat.historyLimit''。设为 ''0'' 禁用（默认 50）。

- 私聊历史上限：''channels.telegram.dmHistoryLimit''（按 user turns 计）。按用户覆盖：''channels.telegram.dms["''"].historyLimit''。

Tutorial.step

群聊触发模式

默认情况下，bot 只会在群里被 mention 时回复（''@botname'' 或 ''agents.list[].groupChat.mentionPatterns'' 命中）。要调整行为：

Tutorial.step

通过配置（推荐）

Json5

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }, // This group always responds
      },
    },
  },
}

''重要：'' 一旦设置了 ''channels.telegram.groups''，它就变成 ''群 allowlist''：只有列出的群（或 ''"*"''）会被接受。

Forum topics 默认继承其父群配置（allowFrom、requireMention、skills、prompts），除非你在 ''channels.telegram.groups.''.topics.'''' 中写 topic 级覆盖。

允许所有群并始终回复：

Json5

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

保持所有群都 require mention（默认行为）：

Json5

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }, // Or omit groups entirely
      },
    },
  },
}

Tutorial.step

通过命令（仅对当前会话生效）

在群里发送：

- ''/activation always'' — 对所有消息回复

- ''/activation mention'' — 需要 mention（默认）

说明：该命令只改变会话状态。要在重启后保持行为，请用配置。

Tutorial.step

获取群 chat ID

把群里的任意消息转发给 ''@userinfobot'' 或 ''@getidsbot''，可看到 chat ID（通常是类似 ''-1001234567890'' 的负数）。

隐私提示：''@userinfobot'' 是第三方 bot。若你不想用第三方，可把 bot 加入群、发一条消息，然后用 ''openclaw logs --follow'' 读取 ''chat.id''，或用 Bot API 的 ''getUpdates''。

Tutorial.step

配置写回（Config writes）

默认情况下，Telegram 允许把由通道事件或 ''/config set|unset'' 触发的配置更新写回配置文件。

典型场景：

- 群被升级为 supergroup，Telegram 发出 ''migrate_to_chat_id''（chat ID 改变）；OpenClaw 可以自动迁移 ''channels.telegram.groups''。

- 你在 Telegram 聊天里运行 ''/config set'' 或 ''/config unset''（需要 ''commands.config: true''）。

禁用：

Json5

{
  channels: { telegram: { configWrites: false } },
}

Tutorial.step

Topics（论坛 supergroup）

Telegram forum topics 每条消息都带 ''message_thread_id''。OpenClaw 会：

Tutorial.step

Inline Buttons（内联按钮）

Telegram 支持 inline keyboard（callback buttons）。

Json5

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

按账号配置：

Json5

{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}

范围（Scopes）：

- ''off'' — 禁用

- ''dm'' — 仅私聊（群目标会被阻止）

- ''group'' — 仅群聊（私聊目标会被阻止）

- ''all'' — 私聊 + 群聊

- ''allowlist'' — 私聊 + 群聊，但仅允许 ''allowFrom''/''groupAllowFrom'' 允许的发送者（与控制命令一致）

默认：''allowlist''。旧写法：''capabilities: ["inlineButtons"]'' 等同于 ''inlineButtons: "all"''。

Tutorial.step

发送按钮

使用消息工具传入 ''buttons'' 参数：

Json5

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}

用户点击按钮后，callback data 会以消息形式回传给 agent：

''callback_data: value''

Tutorial.step

配置层级

Telegram capabilities 可在两层配置（上面示例是对象形式；旧的字符串数组也仍支持）：

- ''channels.telegram.capabilities''：全局默认，应用于所有 Telegram 账号（除非被覆盖）

- ''channels.telegram.accounts.''.capabilities''：按账号覆盖

Tutorial.step

访问控制（私聊 + 群聊）

Tutorial.step

私聊（DM）访问

- 默认：''channels.telegram.dmPolicy = "pairing"''。未知发送者会收到配对码；批准后才处理（1 小时过期）。

- 批准：

- ''openclaw pairing list telegram''

- ''openclaw pairing approve telegram ''''

- pairing 是 Telegram 私聊默认 token exchange。细节见 ''Pairing''。

- ''channels.telegram.allowFrom'' 推荐使用数值 user id，也支持 ''@username''。注意它指的是人类发送者的 ID，而不是 bot 的 username。向导会在可能时把 ''@username'' 解析为数值 id。

#

Tutorial.step如何获取你的 Telegram user ID

更安全（不依赖第三方 bot）：

1. 启动 gateway，给你的 bot 发一条私信。

2. 运行 ''openclaw logs --follow''，找到 ''from.id''。

官方 Bot API（更直接）：

1. 给 bot 发私信。

2. 用 token 调 ''getUpdates'' 并读取 ''message.from.id''：

''''`bash", "p8": "curl "https://api.telegram.org/bot''/getUpdates"", "p9": "''''`

curl "https://api.telegram.org/bot''/getUpdates"

''''`

第三方（隐私较弱）：

- 私信 ''@userinfobot'' 或 ''@getidsbot''。

#

Tutorial.step群聊（Group）访问

群聊有两套独立控制：

''1）允许哪些群''（''channels.telegram.groups'' 作为群 allowlist）：

- 不写 ''groups''：允许所有群

- 写了 ''groups''：只允许列出的群或 ''"*"''

- 例如："groups": { "-1001234567890": {'}, "*": {'} }' 表示允许所有群（同时可对特定群写覆盖）

''2）允许哪些发送者''（''channels.telegram.groupPolicy'' 控制群发送者过滤）：

- ''"open"''：允许群内所有发送者

- ''"allowlist"''：仅允许 ''channels.telegram.groupAllowFrom'' 中的发送者

- ''"disabled"''：完全不接受群消息

默认是 ''groupPolicy: "allowlist"''（即不配置 ''groupAllowFrom'' 时默认阻断）

多数用户想要：''groupPolicy: "allowlist"'' + ''groupAllowFrom'' + 在 ''channels.telegram.groups'' 里列出允许的群。

Tutorial.stepLong-polling 与 Webhook

- 默认：long-polling（不需要公网 URL）。

- Webhook：设置 ''channels.telegram.webhookUrl'' 与 ''channels.telegram.webhookSecret''（可选 ''channels.telegram.webhookPath''）。

- 本地监听默认绑定 ''0.0.0.0:8787''，默认路径 ''POST /telegram-webhook''。

- 如果你的公网 URL 不同，请用反向代理，并把 ''channels.telegram.webhookUrl'' 指向公网端点。

Tutorial.step回复线程化（Reply threading）

Telegram 支持可选的"按触发消息回复"能力（基于 tags）：

- ''[[reply_to_current]]'' —— 回复触发消息

- ''[[reply_to:'']]'' —— 回复指定消息 id

通过 ''channels.telegram.replyToMode'' 控制：

- ''first''（默认）、''all''、''off''。

Tutorial.step音频消息（语音条 vs 音频文件）

Telegram 区分语音条（圆形气泡）与音频文件（带元数据卡片）。为兼容旧行为，OpenClaw 默认发送音频文件。

要在 agent 回复中强制发送语音条，在回复任意位置加入：

- ''[[audio_as_voice]]'' —— 把音频作为语音条发送

该 tag 不会出现在最终投递文本里；其他通道会忽略它。

使用消息工具发送语音条：设置 ''asVoice: true''，并提供语音兼容的音频 ''media'' URL（可不写 ''message''）：

Json5

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}