• tắt chế độ riêng tư qua /setprivacy, hoặc
• làm cho bot trở thành quản trị viên nhóm.

• /setjoingroups để cho phép/từ chối thêm vào nhóm
• /setprivacy cho hành vi hiển thị nhóm

• trò chuyện trực tiếp: xem trước tin nhắn + editMessageText
• nhóm/chủ đề: xem trước tin nhắn + editMessageText

• channels.telegram.streaming là off | partial | block | progress (mặc định: partial)
• progress ánh xạ tới partial trên Telegram (tương thích với tên gọi đa kênh)
• channels.telegram.streamMode cũ và các giá trị boolean streaming được ánh xạ tự động

• DM: OpenClaw giữ cùng một tin nhắn xem trước và thực hiện chỉnh sửa cuối cùng tại chỗ (không có tin nhắn thứ hai)
• nhóm/chủ đề: OpenClaw giữ cùng một tin nhắn xem trước và thực hiện chỉnh sửa cuối cùng tại chỗ (không có tin nhắn thứ hai)

• /reasoning stream gửi lý luận đến bản xem trước trực tiếp trong khi tạo
• câu trả lời cuối cùng được gửi mà không có văn bản lý luận

• Văn bản giống Markdown được hiển thị thành HTML an toàn với Telegram.
• HTML thô của mô hình được thoát để giảm lỗi phân tích cú pháp của Telegram.
• Nếu Telegram từ chối HTML đã phân tích, OpenClaw thử lại dưới dạng văn bản thuần túy.

• commands.native: "auto" bật lệnh gốc cho Telegram

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Tạo một hình ảnh" },
      ],
    },
  },
}

• tên được chuẩn hóa (bỏ dấu / đầu, viết thường)
• mẫu hợp lệ: a-z, 0-9, _, độ dài 1..32
• lệnh tùy chỉnh không thể ghi đè lệnh gốc
• xung đột/trùng lặp bị bỏ qua và ghi lại

• lệnh tùy chỉnh chỉ là mục menu; chúng không tự động thực hiện hành vi
• lệnh plugin/kỹ năng vẫn có thể hoạt động khi được nhập ngay cả khi không hiển thị trong menu Telegram

• setMyCommands failed với BOT_COMMANDS_TOO_MUCH có nghĩa là menu Telegram vẫn tràn sau khi cắt bớt; giảm lệnh plugin/kỹ năng/tùy chỉnh hoặc tắt menu gốc
• setMyCommands failed với lỗi mạng/lấy thường có nghĩa là DNS/HTTPS ra ngoài tới api.telegram.org bị chặn.

​

Lệnh ghép nối thiết bị (plugin device-pair)

1. /pair tạo mã thiết lập
2. dán mã vào ứng dụng iOS
3. /pair pending liệt kê các yêu cầu đang chờ xử lý (bao gồm vai trò/phạm vi)
4. phê duyệt yêu cầu:
   • /pair approve <requestId> để phê duyệt rõ ràng
   • /pair approve khi chỉ có một yêu cầu đang chờ xử lý
   • /pair approve latest cho yêu cầu gần nhất

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

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

• off
• dm
• group
• all
• allowlist (mặc định)

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Chọn một tùy chọn:",
  buttons: [
    [
      { text: "Có", callback_data: "yes" },
      { text: "Không", callback_data: "no" },
    ],
    [{ text: "Hủy", callback_data: "cancel" }],
  ],
}

• sendMessage (to, content, tùy chọn mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, tùy chọn iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (mặc định: tắt)

• [[reply_to_current]] trả lời tin nhắn kích hoạt
• [[reply_to:<id>]] trả lời một ID tin nhắn Telegram cụ thể

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

• khóa phiên chủ đề thêm :topic:<threadId>
• trả lời và gõ nhắm vào chủ đề
• đường dẫn cấu hình chủ đề: channels.telegram.groups.<chatId>.topics.<threadId>

• gửi tin nhắn bỏ qua message_thread_id (Telegram từ chối sendMessage(...thread_id=1))
• hành động gõ vẫn bao gồm message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Chủ đề chung → agent chính
            "3": { agentId: "zu" },        // Chủ đề phát triển → agent zu
            "5": { agentId: "coder" }      // Đánh giá mã → agent coder
          }
        }
      }
    }
  }
}

• bindings[] với type: "acp" và match.channel: "telegram"

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

• /acp spawn <agent> --thread here|auto có thể liên kết chủ đề Telegram hiện tại với một phiên ACP mới.
• Các tin nhắn chủ đề tiếp theo định tuyến trực tiếp đến phiên ACP đã liên kết (không cần /acp steer).
• OpenClaw ghim tin nhắn xác nhận khởi tạo trong chủ đề sau khi liên kết thành công.
• Yêu cầu channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• các cuộc trò chuyện riêng với message_thread_id giữ định tuyến DM nhưng sử dụng khóa phiên nhận thức chủ đề/mục tiêu trả lời.

​

Tin nhắn âm thanh

• mặc định: hành vi tệp âm thanh
• thẻ [[audio_as_voice]] trong câu trả lời agent để buộc gửi ghi chú giọng nói

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

​

Tin nhắn video

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

​

Nhãn dán

• WEBP tĩnh: tải xuống và xử lý (chỗ giữ chỗ <media:sticker>)
• TGS động: bỏ qua
• WEBM video: bỏ qua

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

• ~/.openclaw/telegram/sticker-cache.json

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

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

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

• Telegram reaction added: 👍 by Alice (@alice) on msg 42

• channels.telegram.reactionNotifications: off | own | all (mặc định: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (mặc định: minimal)

• own có nghĩa là phản ứng của người dùng đối với các tin nhắn do bot gửi chỉ (nỗ lực tốt nhất qua bộ nhớ cache tin nhắn đã gửi).
• Các sự kiện phản ứng vẫn tôn trọng các kiểm soát truy cập Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); người gửi không được phép bị loại bỏ.
• Telegram không cung cấp ID chủ đề trong các cập nhật phản ứng.
  • các nhóm không phải diễn đàn định tuyến đến phiên trò chuyện nhóm
  • các nhóm diễn đàn định tuyến đến phiên chủ đề chung của nhóm (:topic:1), không phải chủ đề gốc chính xác

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• emoji nhận dạng agent dự phòng (agents.list[].identity.emoji, nếu không có thì ”👀”)

• Telegram mong đợi emoji unicode (ví dụ ”👀”).
• Sử dụng "" để tắt phản ứng cho một kênh hoặc tài khoản.

• sự kiện di chuyển nhóm (migrate_to_chat_id) để cập nhật channels.telegram.groups
• /config set và /config unset (yêu cầu bật lệnh)

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

• thiết lập channels.telegram.webhookUrl
• thiết lập channels.telegram.webhookSecret (bắt buộc khi URL webhook được thiết lập)
• tùy chọn channels.telegram.webhookPath (mặc định /telegram-webhook)
• tùy chọn channels.telegram.webhookHost (mặc định 127.0.0.1)
• tùy chọn channels.telegram.webhookPort (mặc định 8787)

• channels.telegram.textChunkLimit mặc định là 4000.
• channels.telegram.chunkMode="newline" ưu tiên ranh giới đoạn văn (dòng trống) trước khi chia độ dài.
• channels.telegram.mediaMaxMb (mặc định 100) giới hạn kích thước phương tiện Telegram đến và đi.
• channels.telegram.timeoutSeconds ghi đè thời gian chờ của khách hàng API Telegram (nếu không được đặt, áp dụng mặc định của grammY).
• lịch sử ngữ cảnh nhóm sử dụng channels.telegram.historyLimit hoặc messages.groupChat.historyLimit (mặc định 50); 0 vô hiệu hóa.
• Kiểm soát lịch sử DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• cấu hình channels.telegram.retry áp dụng cho các trợ giúp gửi Telegram (CLI/công cụ/hành động) cho các lỗi API gửi đi có thể khôi phục.

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 "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id cho các chủ đề diễn đàn (hoặc sử dụng mục tiêu :topic:)

• --buttons cho bàn phím nội tuyến khi channels.telegram.capabilities.inlineButtons cho phép
• --force-document để gửi hình ảnh và GIF gửi đi dưới dạng tài liệu thay vì tải lên ảnh hoặc phương tiện động nén

• channels.telegram.actions.sendMessage=false vô hiệu hóa các tin nhắn Telegram gửi đi, bao gồm cả các cuộc thăm dò
• channels.telegram.actions.poll=false vô hiệu hóa việc tạo cuộc thăm dò Telegram trong khi vẫn để lại các lần gửi thông thường được bật

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers
• channels.telegram.execApprovals.target (dm | channel | both, mặc định: dm)
• agentFilter, sessionFilter

• target: "dm" chỉ gửi lời nhắc phê duyệt đến DM của người phê duyệt được cấu hình
• target: "channel" gửi lời nhắc trở lại chat/chủ đề Telegram gốc
• target: "both" gửi đến DM của người phê duyệt và chat/chủ đề gốc

• Nếu requireMention=false, chế độ riêng tư của Telegram phải cho phép khả năng hiển thị đầy đủ.
  • BotFather: /setprivacy -> Tắt
  • sau đó xóa và thêm lại bot vào nhóm
• openclaw channels status cảnh báo khi cấu hình mong đợi tin nhắn nhóm không nhắc đến.
• openclaw channels status --probe có thể kiểm tra ID nhóm dạng số rõ ràng; ký tự đại diện "*" không thể được kiểm tra thành viên.
• kiểm tra phiên nhanh: /activation always.

• khi channels.telegram.groups tồn tại, nhóm phải được liệt kê (hoặc bao gồm "*")
• xác minh thành viên bot trong nhóm
• xem lại nhật ký: openclaw logs --follow để biết lý do bỏ qua

• ủy quyền danh tính người gửi của bạn (ghép nối và/hoặc allowFrom dạng số)
• ủy quyền lệnh vẫn áp dụng ngay cả khi chính sách nhóm là open
• setMyCommands failed với BOT_COMMANDS_TOO_MUCH có nghĩa là menu gốc có quá nhiều mục; giảm lệnh plugin/kỹ năng/tùy chỉnh hoặc tắt menu gốc
• setMyCommands failed với lỗi mạng/lấy thường chỉ ra các vấn đề về khả năng truy cập DNS/HTTPS tới api.telegram.org

• Node 22+ + fetch/proxy tùy chỉnh có thể kích hoạt hành vi hủy bỏ ngay lập tức nếu các loại AbortSignal không khớp.
• Một số máy chủ giải quyết api.telegram.org thành IPv6 trước; egress IPv6 bị hỏng có thể gây ra lỗi API Telegram không liên tục.
• Nếu nhật ký bao gồm TypeError: fetch failed hoặc Network request for 'getUpdates' failed!, OpenClaw hiện thử lại những lỗi này như các lỗi mạng có thể khôi phục.
• Trên các máy chủ VPS với egress/TLS trực tiếp không ổn định, định tuyến các cuộc gọi API Telegram qua channels.telegram.proxy:

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

• Node 22+ mặc định là autoSelectFamily=true (trừ WSL2) và dnsResultOrder=ipv4first.
• Nếu máy chủ của bạn là WSL2 hoặc hoạt động tốt hơn rõ ràng với hành vi chỉ IPv4, buộc chọn họ:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Ghi đè môi trường (tạm thời):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Xác thực câu trả lời DNS:

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