​

Telegram（Bot API）

​

快速设置

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

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

​

Telegram 端设置

​

访问控制与激活

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

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

​

运行时行为

• Telegram 由网关进程拥有。
• 路由是确定性的：Telegram 入站消息回复回 Telegram（模型不选择频道）。
• 入站消息会被规范化为共享频道信封，包含回复元数据和媒体占位符。
• 群组会话按群组 ID 隔离。论坛主题通过追加 :topic:<threadId> 维持主题隔离。
• 私聊消息可能携带 message_thread_id；OpenClaw 使用线程感知的会话键路由，并保留线程 ID 用于回复。
• 长轮询使用 grammY 运行器，支持每聊/线程顺序执行。整体运行器汇聚并发使用 agents.defaults.maxConcurrent。
• Telegram Bot API 不支持已读回执（sendReadReceipts 无效）。

​

功能参考

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git 备份" },
        { command: "generate", description: "创建图像" },
      ],
    },
  },
}

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

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

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "请选择一个选项：",
  buttons: [
    [
      { text: "是", callback_data: "yes" },
      { text: "否", callback_data: "no" },
    ],
    [{ text: "取消", callback_data: "cancel" }],
  ],
}

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // 一般主题 → main 代理
            "3": { agentId: "zu" },        // 开发主题 → zu 代理
            "5": { agentId: "coder" }      // 代码审查 → coder 代理
          }
        }
      }
    }
  }
}

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

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

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

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

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "发货吗？" --poll-option "是" --poll-option "否"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "选个时间" --poll-option "上午10点" --poll-option "下午2点" \
  --poll-duration-seconds 300 --poll-public

​

故障排除

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

channels:
  telegram:
    network:
      autoSelectFamily: false

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

​

Telegram 配置参考指引

• channels.telegram.enabled：启动/禁用频道。
• channels.telegram.botToken：BotFather 机器人令牌。
• channels.telegram.tokenFile：从文件读取令牌。
• channels.telegram.dmPolicy：pairing | allowlist | open | disabled（默认 pairing）。
• channels.telegram.allowFrom：私聊白名单（数字 Telegram 用户 ID）。allowlist 需至少一个发送者 ID；open 需含 "*"。openclaw doctor --fix 可解析遗留的 @用户名，并在白名单迁移时从配对存储恢复条目。
• channels.telegram.actions.poll：启用或禁用 Telegram 投票创建（默认启用，仍需启用发送权限）。
• channels.telegram.defaultTo：CLI --deliver 未显式指定 --reply-to 时的默认 Telegram 目标。
• channels.telegram.groupPolicy：open | allowlist | disabled（默认允许列表）。
• channels.telegram.groupAllowFrom：群组发送者白名单（数字 Telegram 用户 ID）。openclaw doctor --fix 可解析遗留 @用户名。非数字条目授权时忽略。群授权不使用私聊配对存储回退（2026.2.25 及以后）。
• 多账户优先级：
  • 配置多个账户 ID 时，请设置 channels.telegram.defaultAccount（或含 channels.telegram.accounts.default）显式默认路由。
  • 若均未设置，OpenClaw 会回退到首个标准化账户 ID，且 openclaw doctor 会发出警告。
  • channels.telegram.accounts.default.allowFrom 和 channels.telegram.accounts.default.groupAllowFrom 仅应用于默认账户。
  • 命名账户若无账户级允许列表，继承顶层 channels.telegram.allowFrom 和 channels.telegram.groupAllowFrom。
  • 命名账户不继承 channels.telegram.accounts.default.allowFrom / groupAllowFrom。
• channels.telegram.groups：群组默认与白名单（全局默认用 "*"）。
  • channels.telegram.groups.<id>.groupPolicy：群组层级 groupPolicy 覆盖（open | allowlist | disabled）。
  • channels.telegram.groups.<id>.requireMention：提及门控默认值。
  • channels.telegram.groups.<id>.skills：技能过滤（无配置 = 全部，空数组 = 无）。
  • channels.telegram.groups.<id>.allowFrom：群组发送者白名单覆盖。
  • channels.telegram.groups.<id>.systemPrompt：群组额外系统提示。
  • channels.telegram.groups.<id>.enabled：设置为 false 禁用该群组。
  • channels.telegram.groups.<id>.topics.<threadId>.*：主题级覆盖（群组字段与仅主题 agentId）。
  • channels.telegram.groups.<id>.topics.<threadId>.agentId：为指定主题路由特定代理（覆盖群组与绑定路由）。
  • channels.telegram.groups.<id>.topics.<threadId>.groupPolicy：主题级覆盖的群组策略。
  • channels.telegram.groups.<id>.topics.<threadId>.requireMention：主题级提及门控覆盖。
  • 顶层 bindings[]，包含 type: "acp" 与标准主题 ID chatId:topic:topicId 在 match.peer.id 中：持久 ACP 主题绑定字段（详见ACP 代理）。
  • channels.telegram.direct.<id>.topics.<threadId>.agentId：将私聊主题路由到特定代理（行为同论坛主题）。
• channels.telegram.capabilities.inlineButtons：off | dm | group | all | allowlist（默认允许列表）。
• channels.telegram.accounts.<account>.capabilities.inlineButtons：账户级覆盖。
• channels.telegram.commands.nativeSkills：启用/禁用 Telegram 原生技能命令。
• channels.telegram.replyToMode：off | first | all（默认关闭）。
• channels.telegram.textChunkLimit：出站分块大小（字符数）。
• channels.telegram.chunkMode：length（默认）或 newline（优先按空白行分块）。
• channels.telegram.linkPreview：切换出站消息链接预览（默认开启）。
• channels.telegram.streaming：off | partial | block | progress（实时预览；默认 partial，progress 映射为 partial，block 为兼容旧版）。
• channels.telegram.mediaMaxMb：入站媒体下载/处理上限（MB）。
• channels.telegram.retry：Telegram 发送助手（CLI/工具/动作）遇到可恢复 API 错误时的重试策略（重试次数、最小延迟、最大延迟、随机抖动）。
• channels.telegram.network.autoSelectFamily：覆盖 Node 网络族自动选择（true 启用，false 禁用）。Node 22+ 默认启用，WSL2 默认禁用。
• channels.telegram.network.dnsResultOrder：覆盖 DNS 结果排序 (ipv4first 或 verbatim)。Node 22+ 默认 ipv4first。
• channels.telegram.proxy：Bot API 请求代理地址（SOCKS/HTTP）。
• channels.telegram.webhookUrl：开启 webhook 模式（需配置 webhookSecret）。
• channels.telegram.webhookSecret：webhook secret（配置 webhookUrl 时必填）。
• channels.telegram.webhookPath：本地 webhook 路径（默认为 /telegram-webhook）。
• channels.telegram.webhookHost：本地 webhook 绑定主机（默认 127.0.0.1）。
• channels.telegram.webhookPort：本地 webhook 绑定端口（默认 8787）。
• channels.telegram.actions.reactions：控制 Telegram 工具反应权限。
• channels.telegram.actions.sendMessage：控制出站 Telegram 消息发送权限。
• channels.telegram.actions.deleteMessage：控制 Telegram 消息删除权限。
• channels.telegram.actions.sticker：控制 Telegram 贴纸操作权限 — 发送和搜索（默认关闭）。
• channels.telegram.reactionNotifications：off | own | all — 控制哪些反应触发系统事件（默认：own）。
• channels.telegram.reactionLevel：off | ack | minimal | extensive — 控制代理的反应能力（默认：minimal）。
• 配置参考 - Telegram

• 启动/认证：enabled, botToken, tokenFile, accounts.*
• 访问控制：dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*, 顶层 bindings[]（type: "acp"）
• 命令菜单：commands.native, commands.nativeSkills, customCommands
• 线程与回复：replyToMode
• 流式输出：streaming（预览）、blockStreaming
• 格式与投递：textChunkLimit, chunkMode, linkPreview, responsePrefix
• 媒体与网络：mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
• Webhook：webhookUrl, webhookSecret, webhookPath, webhookHost
• 动作与能力：capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
• 反应相关：reactionNotifications, reactionLevel
• 写入与历史记录：configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

​

关联文档

• 配对
• 频道路由
• 多代理路由
• 故障排查