Telegram (Bot API)

Trạng thái: sẵn sàng cho production với bot DM + nhóm qua grammY. Mặc định dùng long-polling; webhook là tùy chọn.

Cài đặt nhanh (người mới)

  1. Tạo bot với @BotFather (link trực tiếp). Xác nhận handle chính xác là @BotFather, sau đó copy token.
  2. Đặt token:
    • Env: TELEGRAM_BOT_TOKEN=...
    • Hoặc config: channels.telegram.botToken: "...".
    • Nếu đặt cả hai, config sẽ được ưu tiên (env fallback chỉ cho default-account).
  3. Khởi động Gateway.
  4. Truy cập DM mặc định là pairing; phê duyệt mã pairing khi liên hệ lần đầu.

Config tối thiểu:

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

Nó là gì

  • Một Telegram Bot API channel thuộc sở hữu của Gateway.
  • Routing xác định: các phản hồi quay lại Telegram; model không bao giờ chọn channel.
  • DM chia sẻ session chính của agent; nhóm được cô lập (agent:<agentId>:telegram:group:<chatId>).

Cài đặt (đường đi nhanh)

1) Tạo bot token (BotFather)

  1. Mở Telegram và chat với @BotFather (link trực tiếp). Xác nhận handle chính xác là @BotFather.
  2. Chạy /newbot, sau đó làm theo hướng dẫn (tên + username kết thúc bằng bot).
  3. Copy token và lưu trữ an toàn.

Cài đặt BotFather tùy chọn:

  • /setjoingroups — cho phép/từ chối thêm bot vào nhóm.
  • /setprivacy — kiểm soát xem bot có thấy tất cả tin nhắn nhóm không.

2) Cấu hình token (env hoặc config)

Ví dụ:

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

Tùy chọn Env: TELEGRAM_BOT_TOKEN=... (hoạt động cho tài khoản mặc định). Nếu đặt cả env và config, config sẽ được ưu tiên.

Hỗ trợ nhiều tài khoản: dùng channels.telegram.accounts với token cho từng tài khoản và name tùy chọn. Xem gateway/configuration cho pattern chung.

  1. Khởi động Gateway. Telegram khởi động khi token được resolve (config trước, env fallback).
  2. Truy cập DM mặc định là pairing. Phê duyệt mã khi bot được liên hệ lần đầu.
  3. Đối với nhóm: thêm bot, quyết định hành vi privacy/admin (bên dưới), sau đó đặt channels.telegram.groups để kiểm soát mention gating + allowlist.

Token + privacy + quyền (phía Telegram)

Tạo token (BotFather)

  • /newbot tạo bot và trả về token (giữ bí mật).
  • Nếu token bị rò rỉ, thu hồi/tạo lại qua @BotFather và cập nhật config của bạn.

Khả năng hiển thị tin nhắn nhóm (Privacy Mode)

Bot Telegram mặc định ở Privacy Mode, giới hạn tin nhắn nhóm mà chúng nhận được. Nếu bot của bạn phải thấy tất cả tin nhắn nhóm, bạn có hai tùy chọn:

  • Tắt privacy mode với /setprivacy hoặc
  • Thêm bot làm admin nhóm (bot admin nhận tất cả tin nhắn).

Lưu ý: Khi bạn chuyển đổi privacy mode, Telegram yêu cầu xóa + thêm lại bot vào mỗi nhóm để thay đổi có hiệu lực.

Quyền nhóm (quyền admin)

Trạng thái admin được đặt bên trong nhóm (Telegram UI). Bot admin luôn nhận tất cả tin nhắn nhóm, vì vậy dùng admin nếu bạn cần khả năng hiển thị đầy đủ.

Cách hoạt động (hành vi)

  • Tin nhắn đến được chuẩn hóa thành channel envelope chung với reply context và media placeholder.
  • Phản hồi nhóm yêu cầu mention theo mặc định (native @mention hoặc agents.list[].groupChat.mentionPatterns / messages.groupChat.mentionPatterns).
  • Override nhiều agent: đặt pattern cho từng agent trên agents.list[].groupChat.mentionPatterns.
  • Phản hồi luôn route lại về cùng một Telegram chat.
  • Long-polling dùng grammY runner với sequencing theo chat; tổng concurrency được giới hạn bởi agents.defaults.maxConcurrent.
  • Telegram Bot API không hỗ trợ read receipt; không có tùy chọn sendReadReceipts.

Draft streaming

OpenClaw có thể stream phản hồi từng phần trong Telegram DM bằng sendMessageDraft.

Yêu cầu:

  • Threaded Mode được bật cho bot trong @BotFather (forum topic mode).
  • Chỉ private chat thread (Telegram bao gồm message_thread_id trên tin nhắn đến).
  • channels.telegram.streamMode không được đặt thành "off" (mặc định: "partial", "block" bật cập nhật draft theo khối).

Draft streaming chỉ dành cho DM; Telegram không hỗ trợ nó trong nhóm hoặc channel.

Định dạng (Telegram HTML)

  • Text Telegram đi ra dùng parse_mode: "HTML" (tập hợp tag được Telegram hỗ trợ).
  • Input kiểu Markdown được render thành Telegram-safe HTML (bold/italic/strike/code/link); các phần tử block được làm phẳng thành text với newline/bullet.
  • HTML thô từ model được escape để tránh lỗi parse Telegram.
  • Nếu Telegram từ chối HTML payload, OpenClaw thử lại cùng tin nhắn dưới dạng plain text.

Lệnh (native + custom)

OpenClaw đăng ký các lệnh native (như /status, /reset, /model) với menu bot Telegram khi khởi động. Các bạn có thể thêm lệnh tùy chỉnh vào menu qua config:

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

Troubleshooting

  • setMyCommands failed trong log thường có nghĩa là HTTPS/DNS đi ra bị chặn đến api.telegram.org.
  • Nếu bạn thấy lỗi sendMessage hoặc sendChatAction, kiểm tra routing IPv6 và DNS.

Trợ giúp thêm: Channel troubleshooting.

Lưu ý:

  • Lệnh tùy chỉnh chỉ là mục menu; OpenClaw không implement chúng trừ khi bạn xử lý ở nơi khác.
  • Tên lệnh được chuẩn hóa (dấu / đầu bị loại bỏ, chữ thường) và phải khớp a-z, 0-9, _ (1–32 ký tự).
  • Lệnh tùy chỉnh không thể override lệnh native. Xung đột bị bỏ qua và ghi log.
  • Nếu commands.native bị tắt, chỉ lệnh tùy chỉnh được đăng ký (hoặc xóa nếu không có).

Giới hạn

  • Text đi ra được chia thành channels.telegram.textChunkLimit (mặc định 4000).
  • Chia theo newline tùy chọn: đặt channels.telegram.chunkMode="newline" để chia trên dòng trống (ranh giới đoạn văn) trước khi chia theo độ dài.
  • Download/upload media được giới hạn bởi channels.telegram.mediaMaxMb (mặc định 5).
  • Request Telegram Bot API timeout sau channels.telegram.timeoutSeconds (mặc định 500 qua grammY). Đặt thấp hơn để tránh treo lâu.
  • Context lịch sử nhóm dùng channels.telegram.historyLimit (hoặc channels.telegram.accounts.*.historyLimit), fallback về messages.groupChat.historyLimit. Đặt 0 để tắt (mặc định 50).
  • Lịch sử DM có thể được giới hạn với channels.telegram.dmHistoryLimit (lượt người dùng). Override theo người dùng: channels.telegram.dms["<user_id>"].historyLimit.

Chế độ kích hoạt nhóm

Mặc định, bot chỉ phản hồi mention trong nhóm (@botname hoặc pattern trong agents.list[].groupChat.mentionPatterns). Để thay đổi hành vi này:

Qua config (khuyên dùng)

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }, // luôn phản hồi trong nhóm này
      },
    },
  },
}

Quan trọng: Đặt channels.telegram.groups tạo một allowlist - chỉ các nhóm được liệt kê (hoặc "*") sẽ được chấp nhận. Forum topic kế thừa config nhóm cha (allowFrom, requireMention, skills, prompts) trừ khi bạn thêm override cho từng topic dưới channels.telegram.groups.<groupId>.topics.<topicId>.

Để cho phép tất cả nhóm với always-respond:

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }, // tất cả nhóm, luôn phản hồi
      },
    },
  },
}

Để giữ mention-only cho tất cả nhóm (hành vi mặc định):

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }, // hoặc bỏ qua groups hoàn toàn
      },
    },
  },
}

Qua lệnh (cấp session)

Gửi trong nhóm:

  • /activation always - phản hồi tất cả tin nhắn
  • /activation mention - yêu cầu mention (mặc định)

Lưu ý: Lệnh chỉ cập nhật trạng thái session. Để có hành vi bền vững qua các lần khởi động lại, dùng config.

Lấy group chat ID

Forward bất kỳ tin nhắn nào từ nhóm đến @userinfobot hoặc @getidsbot trên Telegram để xem chat ID (số âm như -1001234567890).

Mẹo: Để lấy user ID của bạn, DM bot và nó sẽ trả lời với user ID của bạn (tin nhắn pairing), hoặc dùng /whoami khi lệnh được bật.

Lưu ý về privacy: @userinfobot là bot của bên thứ ba. Nếu bạn muốn, thêm bot vào nhóm, gửi tin nhắn, và dùng openclaw logs --follow để đọc chat.id, hoặc dùng Bot API getUpdates.

Ghi config

Mặc định, Telegram được phép ghi cập nhật config được kích hoạt bởi sự kiện channel hoặc /config set|unset.

Điều này xảy ra khi:

  • Một nhóm được nâng cấp lên supergroup và Telegram phát ra migrate_to_chat_id (chat ID thay đổi). OpenClaw có thể migrate channels.telegram.groups tự động.
  • Bạn chạy /config set hoặc /config unset trong Telegram chat (yêu cầu commands.config: true).

Tắt với:

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

Topic (forum supergroup)

Telegram forum topic bao gồm message_thread_id cho mỗi tin nhắn. OpenClaw:

  • Thêm :topic:<threadId> vào Telegram group session key để mỗi topic được cô lập.
  • Gửi typing indicator và phản hồi với message_thread_id để phản hồi ở trong topic.
  • General topic (thread id 1) đặc biệt: gửi tin nhắn bỏ qua message_thread_id (Telegram từ chối nó), nhưng typing indicator vẫn bao gồm nó.
  • Expose MessageThreadId + IsForum trong template context cho routing/templating.
  • Cấu hình cụ thể cho topic có sẵn dưới channels.telegram.groups.<chatId>.topics.<threadId> (skill, allowlist, auto-reply, system prompt, disable).
  • Config topic kế thừa cài đặt nhóm (requireMention, allowlist, skill, prompt, enabled) trừ khi được override cho từng topic.

Private chat có thể bao gồm message_thread_id trong một số trường hợp đặc biệt. OpenClaw giữ DM session key không thay đổi, nhưng vẫn dùng thread id cho phản hồi/draft streaming khi nó có mặt.

Nút Inline

Telegram hỗ trợ bàn phím inline với nút callback.

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

Để cấu hình theo tài khoản:

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

Phạm vi:

  • off — nút inline bị tắt
  • dm — chỉ DM (target nhóm bị chặn)
  • group — chỉ nhóm (target DM bị chặn)
  • all — DM + nhóm
  • allowlist — DM + nhóm, nhưng chỉ người gửi được phép bởi allowFrom/groupAllowFrom (cùng quy tắc với lệnh điều khiển)

Mặc định: allowlist. Legacy: capabilities: ["inlineButtons"] = inlineButtons: "all".

Gửi nút

Dùng message tool với tham số buttons:

{
  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" }],
  ],
}

Khi người dùng click nút, callback data được gửi lại cho agent dưới dạng tin nhắn với định dạng: callback_data: value

Tùy chọn cấu hình

Telegram capabilities có thể được cấu hình ở hai cấp (dạng object hiển thị ở trên; mảng string legacy vẫn được hỗ trợ):

  • channels.telegram.capabilities: Config capability mặc định toàn cục áp dụng cho tất cả tài khoản Telegram trừ khi được override.
  • channels.telegram.accounts.<account>.capabilities: Capability theo tài khoản override mặc định toàn cục cho tài khoản cụ thể đó.

Dùng cài đặt toàn cục khi tất cả bot/tài khoản Telegram nên hoạt động giống nhau. Dùng cấu hình theo tài khoản khi các bot khác nhau cần hành vi khác nhau (ví dụ, một tài khoản chỉ xử lý DM trong khi tài khoản khác được phép trong nhóm).

Kiểm soát truy cập (DM + nhóm)

Truy cập DM

  • Mặc định: channels.telegram.dmPolicy = "pairing". Người gửi không xác định nhận mã pairing; tin nhắn bị bỏ qua cho đến khi được phê duyệt (mã hết hạn sau 1 giờ).
  • Phê duyệt qua:
    • openclaw pairing list telegram
    • openclaw pairing approve telegram <CODE>
  • Pairing là token exchange mặc định được dùng cho Telegram DM. Chi tiết: Pairing
  • channels.telegram.allowFrom chấp nhận user ID số (khuyên dùng) hoặc mục @username. Đây không phải là bot username; dùng ID của người gửi. Wizard chấp nhận @username và resolve nó thành ID số khi có thể.

Tìm Telegram user ID của bạn

An toàn hơn (không có bot bên thứ ba):

  1. Khởi động Gateway và DM bot của bạn.
  2. Chạy openclaw logs --follow và tìm from.id.

Thay thế (Bot API chính thức):

  1. DM bot của bạn.
  2. Fetch update với bot token của bạn và đọc message.from.id: 
    curl "https://api.telegram.org/bot<bot_token>/getUpdates"

Bên thứ ba (ít riêng tư hơn):

  • DM @userinfobot hoặc @getidsbot và dùng user id được trả về.

Truy cập nhóm

Hai điều khiển độc lập:

1. Nhóm nào được phép (group allowlist qua channels.telegram.groups):

  • Không có config groups = tất cả nhóm được phép
  • Với config groups = chỉ nhóm được liệt kê hoặc "*" được phép
  • Ví dụ: "groups": { "-1001234567890": {}, "*": {} } cho phép tất cả nhóm

2. Người gửi nào được phép (lọc người gửi qua channels.telegram.groupPolicy):

  • "open" = tất cả người gửi trong nhóm được phép có thể nhắn tin
  • "allowlist" = chỉ người gửi trong channels.telegram.groupAllowFrom có thể nhắn tin
  • "disabled" = không chấp nhận tin nhắn nhóm nào cả Mặc định là groupPolicy: "allowlist" (bị chặn trừ khi bạn thêm groupAllowFrom).

Hầu hết người dùng muốn: groupPolicy: "allowlist" + groupAllowFrom + nhóm cụ thể được liệt kê trong channels.telegram.groups

Long-polling vs webhook

  • Mặc định: long-polling (không cần URL công khai).
  • Chế độ webhook: đặt channels.telegram.webhookUrl và channels.telegram.webhookSecret (tùy chọn channels.telegram.webhookPath).
    • Listener local bind vào 0.0.0.0:8787 và phục vụ POST /telegram-webhook theo mặc định.
    • Nếu URL công khai của bạn khác, dùng reverse proxy và trỏ channels.telegram.webhookUrl vào endpoint công khai.

Reply threading

Telegram hỗ trợ reply có luồng tùy chọn qua tag:

  • [[reply_to_current]] — reply tin nhắn kích hoạt.
  • [[reply_to:<id>]] — reply tin nhắn id cụ thể.

Được kiểm soát bởi channels.telegram.replyToMode:

  • first (mặc định), all, off.

Tin nhắn audio (voice vs file)

Telegram phân biệt voice note (bong bóng tròn) với audio file (thẻ metadata). OpenClaw mặc định là audio file để tương thích ngược.

Để buộc bong bóng voice note trong phản hồi agent, bao gồm tag này ở bất kỳ đâu trong phản hồi:

  • [[audio_as_voice]] — gửi audio dưới dạng voice note thay vì file.

Tag bị loại bỏ khỏi text được gửi. Các channel khác bỏ qua tag này.

Để gửi message tool, đặt asVoice: true với URL media audio tương thích voice (message là tùy chọn khi media có mặt):

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

Sticker

OpenClaw hỗ trợ nhận và gửi Telegram sticker với caching thông minh.

Nhận sticker

Khi người dùng gửi sticker, OpenClaw xử lý nó dựa trên loại sticker:

  • Sticker tĩnh (WEBP): Được download và xử lý qua vision. Sticker xuất hiện dưới dạng placeholder <media:sticker> trong nội dung tin nhắn.
  • Sticker động (TGS): Bị bỏ qua (định dạng Lottie không được hỗ trợ để xử lý).
  • Sticker video (WEBM): Bị bỏ qua (định dạng video không được hỗ trợ để xử lý).

Trường template context có sẵn khi nhận sticker:

  • Sticker — object với:
    • emoji — emoji liên kết với sticker
    • setName — tên của sticker set
    • fileId — Telegram file ID (gửi lại cùng sticker)
    • fileUniqueId — ID ổn định cho cache lookup
    • cachedDescription — mô tả vision được cache khi có sẵn

Cache sticker

Sticker được xử lý qua khả năng vision của AI để tạo mô tả. Vì cùng sticker thường được gửi lặp lại, OpenClaw cache các mô tả này để tránh các API call dư thừa.

Cách hoạt động:

  1. Lần gặp đầu tiên: Hình ảnh sticker được gửi đến AI để phân tích vision. AI tạo mô tả (ví dụ: “A cartoon cat waving enthusiastically”).
  2. Lưu trữ cache: Mô tả được lưu cùng với file ID, emoji và tên set của sticker.
  3. Các lần gặp tiếp theo: Khi cùng sticker được thấy lại, mô tả được cache được dùng trực tiếp. Hình ảnh không được gửi đến AI.

Vị trí cache: ~/.openclaw/telegram/sticker-cache.json

Định dạng cache entry:

{
  "fileId": "CAACAgIAAxkBAAI...",
  "fileUniqueId": "AgADBAADb6cxG2Y",
  "emoji": "👋",
  "setName": "CoolCats",
  "description": "A cartoon cat waving enthusiastically",
  "cachedAt": "2026-01-15T10:30:00.000Z"
}

Lợi ích:

  • Giảm chi phí API bằng cách tránh các vision call lặp lại cho cùng sticker
  • Thời gian phản hồi nhanh hơn cho sticker được cache (không có độ trễ xử lý vision)
  • Bật chức năng tìm kiếm sticker dựa trên mô tả được cache

Cache được điền tự động khi sticker được nhận. Không cần quản lý cache thủ công.

Gửi sticker

Agent có thể gửi và tìm kiếm sticker bằng action sticker và sticker-search. Chúng bị tắt theo mặc định và phải được bật trong config:

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

Gửi sticker:

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

Tham số:

  • fileId (bắt buộc) — Telegram file ID của sticker. Lấy từ Sticker.fileId khi nhận sticker, hoặc từ kết quả sticker-search.
  • replyTo (tùy chọn) — message ID để reply.
  • threadId (tùy chọn) — message thread ID cho forum topic.

Tìm kiếm sticker:

Agent có thể tìm kiếm sticker được cache theo mô tả, emoji hoặc tên set:

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

Trả về sticker khớp từ cache:

{
  ok: true,
  count: 2,
  stickers: [
    {
      fileId: "CAACAgIAAxkBAAI...",
      emoji: "👋",
      description: "A cartoon cat waving enthusiastically",
      setName: "CoolCats",
    },
  ],
}

Tìm kiếm dùng fuzzy matching trên text mô tả, ký tự emoji và tên set.

Ví dụ với threading:

{
  action: "sticker",
  channel: "telegram",
  to: "-1001234567890",
  fileId: "CAACAgIAAxkBAAI...",
  replyTo: 42,
  threadId: 123,
}

Streaming (draft)

Telegram có thể stream draft bubble trong khi agent đang tạo phản hồi. OpenClaw dùng Bot API sendMessageDraft (không phải tin nhắn thật) và sau đó gửi phản hồi cuối cùng dưới dạng tin nhắn bình thường.

Yêu cầu (Telegram Bot API 9.3+):

  • Private chat với topic được bật (forum topic mode cho bot).
  • Tin nhắn đến phải bao gồm message_thread_id (private topic thread).
  • Streaming bị bỏ qua cho nhóm/supergroup/channel.

Config:

  • channels.telegram.streamMode: "off" | "partial" | "block" (mặc định: partial)
    • partial: cập nhật draft bubble với text streaming mới nhất.
    • block: cập nhật draft bubble theo khối lớn hơn (chunked).
    • off: tắt draft streaming.
  • Tùy chọn (chỉ cho streamMode: "block"):
    • channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }
      • mặc định: minChars: 200, maxChars: 800, breakPreference: "paragraph" (giới hạn ở channels.telegram.textChunkLimit).

Lưu ý: draft streaming tách biệt với block streaming (tin nhắn channel). Block streaming tắt theo mặc định và yêu cầu channels.telegram.blockStreaming: true nếu bạn muốn tin nhắn Telegram sớm thay vì cập nhật draft.

Reasoning stream (chỉ Telegram):

  • /reasoning stream stream reasoning vào draft bubble trong khi phản hồi đang tạo, sau đó gửi câu trả lời cuối cùng không có reasoning.
  • Nếu channels.telegram.streamMode là off, reasoning stream bị tắt. Thêm ngữ cảnh: Streaming + chunking.

Retry policy

Các API call Telegram đi ra thử lại trên lỗi network/429 tạm thời với exponential backoff và jitter. Cấu hình qua channels.telegram.retry. Xem Retry policy.

Agent tool (tin nhắn + reaction)

  • Tool: telegram với action sendMessage (to, content, tùy chọn mediaUrl, replyToMessageId, messageThreadId).
  • Tool: telegram với action react (chatId, messageId, emoji).
  • Tool: telegram với action deleteMessage (chatId, messageId).
  • Ngữ nghĩa xóa reaction: xem /tools/reactions.
  • Gating tool: channels.telegram.actions.reactions, channels.telegram.actions.sendMessage, channels.telegram.actions.deleteMessage (mặc định: enabled), và channels.telegram.actions.sticker (mặc định: disabled).

Thông báo reaction

Cách reaction hoạt động: Telegram reaction đến dưới dạng sự kiện message_reaction riêng biệt, không phải là thuộc tính trong message payload. Khi người dùng thêm reaction, OpenClaw:

  1. Nhận cập nhật message_reaction từ Telegram API
  2. Chuyển đổi nó thành sự kiện hệ thống với định dạng: "Telegram reaction added: {emoji} by {user} on msg {id}"
  3. Đưa sự kiện hệ thống vào hàng đợi bằng cùng session key với tin nhắn thông thường
  4. Khi tin nhắn tiếp theo đến trong cuộc trò chuyện đó, các sự kiện hệ thống được lấy ra và thêm vào đầu context của agent

Agent thấy reaction dưới dạng thông báo hệ thống trong lịch sử cuộc trò chuyện, không phải là metadata tin nhắn.

Cấu hình:

  • channels.telegram.reactionNotifications: Kiểm soát reaction nào kích hoạt thông báo

    • "off" — bỏ qua tất cả reaction
    • "own" — thông báo khi người dùng react tin nhắn bot (best-effort; in-memory) (mặc định)
    • "all" — thông báo cho tất cả reaction

  • channels.telegram.reactionLevel: Kiểm soát khả năng reaction của agent

    • "off" — agent không thể react tin nhắn
    • "ack" — bot gửi acknowledgment reaction (👀 trong khi xử lý) (mặc định)
    • "minimal" — agent có thể react ít (hướng dẫn: 1 mỗi 5-10 trao đổi)
    • "extensive" — agent có thể react tự do khi phù hợp

Forum group: Reaction trong forum group bao gồm message_thread_id và dùng session key như agent:main:telegram:group:{chatId}:topic:{threadId}. Điều này đảm bảo reaction và tin nhắn trong cùng topic ở cùng nhau.

Ví dụ config:

{
  channels: {
    telegram: {
      reactionNotifications: "all", // Xem tất cả reaction
      reactionLevel: "minimal", // Agent có thể react ít
    },
  },
}

Yêu cầu:

  • Bot Telegram phải yêu cầu rõ ràng message_reaction trong allowed_updates (được OpenClaw cấu hình tự động)
  • Đối với chế độ webhook, reaction được bao gồm trong webhook allowed_updates
  • Đối với chế độ polling, reaction được bao gồm trong getUpdates allowed_updates

Target gửi (CLI/cron)

  • Dùng chat id (123456789) hoặc username (@name) làm target.
  • Ví dụ: openclaw message send --channel telegram --target 123456789 --message "hi".

Troubleshooting

Bot không phản hồi tin nhắn không mention trong nhóm:

  • Nếu bạn đặt channels.telegram.groups.*.requireMention=false, privacy mode của Telegram Bot API phải bị tắt.
    • BotFather: /setprivacy → Disable (sau đó xóa + thêm lại bot vào nhóm)
  • openclaw channels status hiển thị cảnh báo khi config mong đợi tin nhắn nhóm không mention.
  • openclaw channels status --probe có thể kiểm tra thêm membership cho group ID số rõ ràng (không thể audit quy tắc wildcard "*").
  • Test nhanh: /activation always (chỉ session; dùng config để bền vững)

Bot không thấy tin nhắn nhóm:

  • Nếu channels.telegram.groups được đặt, nhóm phải được liệt kê hoặc dùng "*"
  • Kiểm tra Privacy Settings trong @BotFather → “Group Privacy” nên là OFF
  • Xác minh bot thực sự là thành viên (không chỉ admin không có quyền đọc)
  • Kiểm tra gateway log: openclaw logs --follow (tìm “skipping group message”)

Bot phản hồi mention nhưng không phản hồi /activation always:

  • Lệnh /activation cập nhật trạng thái session nhưng không lưu vào config
  • Để có hành vi bền vững, thêm nhóm vào channels.telegram.groups với requireMention: false

Lệnh như /status không hoạt động:

  • Đảm bảo Telegram user ID của bạn được ủy quyền (qua pairing hoặc channels.telegram.allowFrom)
  • Lệnh yêu cầu ủy quyền ngay cả trong nhóm với groupPolicy: "open"

Long-polling dừng ngay lập tức trên Node 22+ (thường với proxy/custom fetch):

  • Node 22+ nghiêm ngặt hơn về instance AbortSignal; signal ngoại lai có thể dừng fetch call ngay lập tức.
  • Nâng cấp lên bản OpenClaw chuẩn hóa abort signal, hoặc chạy Gateway trên Node 20 cho đến khi bạn có thể nâng cấp.

Bot khởi động, sau đó ngừng phản hồi im lặng (hoặc log HttpError: Network request ... failed):

  • Một số host resolve api.telegram.org thành IPv6 trước. Nếu server của bạn không có IPv6 egress hoạt động, grammY có thể bị kẹt trên request chỉ IPv6.
  • Sửa bằng cách bật IPv6 egress hoặc buộc resolve IPv4 cho api.telegram.org (ví dụ, thêm mục /etc/hosts dùng A record IPv4, hoặc ưu tiên IPv4 trong DNS stack OS của bạn), sau đó khởi động lại Gateway.
  • Kiểm tra nhanh: dig +short api.telegram.org A và dig +short api.telegram.org AAAA để xác nhận DNS trả về gì.

Tham chiếu cấu hình (Telegram)

Cấu hình đầy đủ: Configuration

Tùy chọn provider:

  • channels.telegram.enabled: bật/tắt khởi động channel.
  • channels.telegram.botToken: bot token (BotFather).
  • channels.telegram.tokenFile: đọc token từ đường dẫn file.
  • channels.telegram.dmPolicy: pairing | allowlist | open | disabled (mặc định: pairing).
  • channels.telegram.allowFrom: DM allowlist (id/username). open yêu cầu "*".
  • channels.telegram.groupPolicy: open | allowlist | disabled (mặc định: allowlist).
  • channels.telegram.groupAllowFrom: group sender allowlist (id/username).
  • channels.telegram.groups: mặc định theo nhóm + allowlist (dùng "*" cho mặc định toàn cục).
    • channels.telegram.groups.<id>.requireMention: mention gating mặc định.
    • channels.telegram.groups.<id>.skills: bộ lọc skill (bỏ qua = tất cả skill, rỗng = không có).
    • channels.telegram.groups.<id>.allowFrom: override allowlist người gửi theo nhóm.
    • channels.telegram.groups.<id>.systemPrompt: system prompt thêm cho nhóm.
    • channels.telegram.groups.<id>.enabled: tắt nhóm khi false.
    • channels.telegram.groups.<id>.topics.<threadId>.*: override theo topic (cùng trường với nhóm).
    • channels.telegram.groups.<id>.topics.<threadId>.requireMention: override mention gating theo topic.
  • channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (mặc định: allowlist).
  • channels.telegram.accounts.<account>.capabilities.inlineButtons: override theo tài khoản.
  • channels.telegram.replyToMode: off | first | all (mặc định: first).
  • channels.telegram.textChunkLimit: kích thước chunk đi ra (ký tự).
  • channels.telegram.chunkMode: length (mặc định) hoặc newline để chia trên dòng trống (ranh giới đoạn văn) trước khi chia theo độ dài.
  • channels.telegram.linkPreview: bật/tắt link preview cho tin nhắn đi ra (mặc định: true).
  • channels.telegram.streamMode: off | partial | block (draft streaming).
  • channels.telegram.mediaMaxMb: giới hạn media vào/ra (MB).
  • channels.telegram.retry: retry policy cho Telegram API call đi ra (attempts, minDelayMs, maxDelayMs, jitter).
  • channels.telegram.network.autoSelectFamily: override Node autoSelectFamily (true=bật, false=tắt). Mặc định tắt trên Node 22 để tránh Happy Eyeballs timeout.
  • channels.telegram.proxy: proxy URL cho Bot API call (SOCKS/HTTP).
  • channels.telegram.webhookUrl: bật chế độ webhook (yêu cầu channels.telegram.webhookSecret).
  • channels.telegram.webhookSecret: webhook secret (bắt buộc khi webhookUrl được đặt).
  • channels.telegram.webhookPath: đường dẫn webhook local (mặc định /telegram-webhook).
  • channels.telegram.actions.reactions: gate Telegram tool reaction.
  • channels.telegram.actions.sendMessage: gate Telegram tool message send.
  • channels.telegram.actions.deleteMessage: gate Telegram tool message delete.
  • channels.telegram.actions.sticker: gate Telegram sticker action — send và search (mặc định: false).
  • channels.telegram.reactionNotifications: off | own | all — kiểm soát reaction nào kích hoạt sự kiện hệ thống (mặc định: own khi không đặt).
  • channels.telegram.reactionLevel: off | ack | minimal | extensive — kiểm soát khả năng reaction của agent (mặc định: minimal khi không đặt).

Tùy chọn toàn cục liên quan:

  • agents.list[].groupChat.mentionPatterns (pattern mention gating).
  • messages.groupChat.mentionPatterns (fallback toàn cục).
  • commands.native (mặc định "auto" → bật cho Telegram/Discord, tắt cho Slack), commands.text, commands.useAccessGroups (hành vi lệnh). Override với channels.telegram.commands.native.
  • messages.responsePrefix, messages.ackReaction, messages.ackReactionScope, messages.removeAckAfterReply.