Telegram

• tắt chế độ riêng tư qua /setprivacy, hoặc
• đặt bot làm 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ị trong nhóm

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

• channels.telegram.streaming là off | partial | block | progress (mặc định: partial)
• progress ánh xạ sang partial trên Telegram (tương thích với cách đặt tên liên kênh)
• streaming.preview.toolProgress kiểm soát việc cập nhật công cụ/tiến trình có tái sử dụng cùng tin nhắn xem trước đã chỉnh sửa hay không (mặc định: true khi stream xem trước đang hoạt động)
• channels.telegram.streamMode cũ và các giá trị boolean streaming được phát hiện; chạy openclaw doctor --fix để di chuyển chúng sang channels.telegram.streaming.mode

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": false
        }
      }
    }
  }
}

• bản xem trước ngắn cho DM/nhóm/chủ đề: OpenClaw giữ nguyên thông báo xem trước và thực hiện chỉnh sửa cuối cùng tại chỗ
• bản xem trước cũ hơn khoảng một phút: OpenClaw gửi câu trả lời đã hoàn tất dưới dạng thông báo cuối mới rồi dọn dẹp bản xem trước, để dấu thời gian hiển thị của Telegram phản ánh thời điểm hoàn tất thay vì thời điểm tạo bản xem trước

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

• Văn bản kiểu Markdown được kết xuất thành HTML an toàn cho Telegram.
• HTML thô từ mô hình được thoát ký 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 cú pháp, OpenClaw thử lại dưới dạng văn bản thuần.

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

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

• tên được chuẩn hóa (bỏ / ở đầu, chuyển thành chữ 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à được ghi log

• lệnh tùy chỉnh chỉ là mục menu; chúng không tự động triển khai hành vi
• lệnh Plugin/Skills 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 nghĩa là menu Telegram vẫn bị tràn sau khi cắt bớt; hãy giảm lệnh Plugin/Skills/tùy chỉnh hoặc tắt channels.telegram.commands.native.
• deleteWebhook, deleteMyCommands, hoặc setMyCommands thất bại với 404: Not Found trong khi các lệnh curl Bot API trực tiếp vẫn hoạt động có thể nghĩa là channels.telegram.apiRoot đã được đặt thành endpoint đầy đủ /bot<TOKEN>. apiRoot chỉ được là gốc Bot API, và openclaw doctor --fix sẽ xóa phần /bot<TOKEN> vô tình ở cuối.
• getMe returned 401 nghĩa là Telegram từ chối token bot đã cấu hình. Cập nhật botToken, tokenFile, hoặc TELEGRAM_BOT_TOKEN bằng token BotFather hiện tại; OpenClaw dừng trước khi polling nên lỗi này không được báo cáo là lỗi dọn dẹp Webhook.
• setMyCommands failed với lỗi mạng/fetch thường nghĩa là DNS/HTTPS gửi ra 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ờ (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ờ
   • /pair approve latest cho yêu cầu gần đây 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: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", 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 thông báo kích hoạt
• [[reply_to:<id>]] trả lời một ID thông báo Telegram cụ thể

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

• khóa phiên chủ đề nối thêm :topic:<threadId>
• câu trả lời và trạng thái đang nhập nhắm tới luồng chủ đề
• đường dẫn cấu hình chủ đề: channels.telegram.groups.<chatId>.topics.<threadId>

• gửi thông báo bỏ qua message_thread_id (Telegram từ chối sendMessage(...thread_id=1))
• hành động đang nhập vẫn bao gồm message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}

​

Thông báo âm thanh

• mặc định: hành vi tệp âm thanh
• thẻ [[audio_as_voice]] trong câu trả lời của agent để buộc gửi dưới dạng ghi chú thoại
• bản chép lời ghi chú thoại gửi vào được đóng khung là văn bản do máy tạo, không đáng tin cậy trong ngữ cảnh agent; phát hiện lượt nhắc vẫn dùng bản chép lời thô nên thông báo thoại bị chặn theo lượt nhắc tiếp tục hoạt động.

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

​

Thông báo video

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

​

Nhãn dán

• WEBP tĩnh: được tải xuống và xử lý (placeholder <media:sticker>)
• TGS động: bị bỏ qua
• WEBM video: bị 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 nghĩa là chỉ các phản ứng của người dùng đối với tin nhắn do bot gửi (nỗ lực tối đa qua bộ nhớ đệm tin nhắn đã gửi).
• Sự kiện phản ứng vẫn tuân thủ các kiểm soát truy cập của Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); người gửi không được phép sẽ bị loại bỏ.
• Telegram không cung cấp ID luồng trong các bản cập nhật phản ứng.
  • nhóm không phải diễn đàn được định tuyến đến phiên trò chuyện nhóm
  • nhóm diễn đàn được định tuyến đến phiên chủ đề chung của nhóm (:topic:1), không phải đúng chủ đề nguồn ban đầu

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• phương án dự phòng emoji danh tính agent (agents.list[].identity.emoji, nếu không thì ”👀”)

• Telegram yêu cầu emoji unicode (ví dụ ”👀”).
• 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,
    },
  },
}

• 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 tách theo độ dài.
• channels.telegram.mediaMaxMb (mặc định 100) giới hạn kích thước media Telegram vào và ra.
• channels.telegram.timeoutSeconds ghi đè thời gian chờ của client Telegram API (nếu chưa đặt, dùng mặc định của grammY).
• channels.telegram.pollingStallThresholdMs mặc định là 120000; chỉ điều chỉnh trong khoảng 30000 đến 600000 cho các lần khởi động lại polling-stall dương tính giả.
• lịch sử ngữ cảnh nhóm dùng channels.telegram.historyLimit hoặc messages.groupChat.historyLimit (mặc định 50); 0 sẽ tắt.
• ngữ cảnh bổ sung từ trả lời/trích dẫn/chuyển tiếp hiện được truyền nguyên như đã nhận.
• allowlist Telegram chủ yếu kiểm soát ai có thể kích hoạt agent, không phải là một ranh giới biên tập lại ngữ cảnh bổ sung đầy đủ.
• Điều khiển 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 helper gửi Telegram (CLI/công cụ/hành động) đối với lỗi API gửi đi có thể phục hồi. Giao hàng phản hồi cuối cùng chiều đến cũng dùng cơ chế thử lại safe-send có giới hạn cho lỗi Telegram trước kết nối, nhưng không thử lại các envelope mạng không rõ ràng sau khi gửi vì có thể nhân đôi tin nhắn hiển thị.

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 chủ đề diễn đàn (hoặc dùng mục tiêu :topic:)

• --presentation với các khối buttons cho bàn phím inline khi channels.telegram.capabilities.inlineButtons cho phép
• --pin hoặc --delivery '{"pin":true}' để yêu cầu giao hàng được ghim khi bot có thể ghim trong chat đó
• --force-document để gửi ảnh và GIF ra dưới dạng tài liệu thay vì ảnh nén hoặc tải lên media động

• channels.telegram.actions.sendMessage=false tắt tin nhắn Telegram gửi ra, bao gồm cả poll
• channels.telegram.actions.poll=false tắt tạo poll Telegram trong khi vẫn bật gửi thông thường

• channels.telegram.execApprovals.enabled (tự động bật khi phân giải được ít nhất một người phê duyệt)
• channels.telegram.execApprovals.approvers (dự phòng về ID chủ sở hữu dạng số từ commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (mặc định) | channel | both
• agentFilter, sessionFilter

• Nếu requireMention=false, chế độ riêng tư của Telegram phải cho phép hiển thị đầy đủ.
  • BotFather: /setprivacy -> Disable
  • sau đó gỡ bot khỏi nhóm rồi thêm lại
• openclaw channels status cảnh báo khi cấu hình mong đợi tin nhắn nhóm không nhắc đến bot.
• openclaw channels status --probe có thể kiểm tra ID nhóm dạng số rõ ràng; wildcard "*" không thể được kiểm tra tư cách 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 tư cách thành viên của 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 cặp 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 nghĩa là menu gốc có quá nhiều mục; giảm số lệnh Plugin/skill/tùy chỉnh hoặc tắt menu gốc
• Các lệnh khởi động deleteMyCommands / setMyCommands có giới hạn và thử lại một lần qua phương án dự phòng transport của Telegram khi yêu cầu hết thời gian chờ. Lỗi mạng/fetch kéo dài thường cho thấy vấn đề DNS/HTTPS tới api.telegram.org

• getMe returned 401 là lỗi xác thực Telegram đối với token bot đã cấu hình.
• Sao chép lại hoặc tạo lại token bot trong BotFather, rồi cập nhật channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken, hoặc TELEGRAM_BOT_TOKEN cho tài khoản mặc định.
• deleteWebhook 401 Unauthorized trong lúc khởi động cũng là lỗi xác thực; xem nó như “không có webhook tồn tại” sẽ chỉ trì hoãn cùng lỗi token xấu đó sang các lệnh gọi API sau.
• Nếu deleteWebhook thất bại với lỗi mạng tạm thời trong khi khởi động polling, OpenClaw kiểm tra getWebhookInfo; khi Telegram báo URL webhook trống, polling tiếp tục vì việc dọn dẹp đã được thỏa mãn.

• Node 22+ + fetch/proxy tùy chỉnh có thể kích hoạt hành vi hủy ngay lập tức nếu các kiểu AbortSignal không khớp.
• Một số host phân giải api.telegram.org sang IPv6 trước; lưu lượng đi ra IPv6 bị lỗi có thể gây lỗi API Telegram gián đoạn.
• Nếu log bao gồm TypeError: fetch failed hoặc Network request for 'getUpdates' failed!, OpenClaw hiện thử lại các lỗi này như lỗi mạng có thể khôi phục.
• Nếu log bao gồm Polling stall detected, theo mặc định OpenClaw khởi động lại polling và dựng lại transport Telegram sau 120 giây không có long-poll hoàn tất để chứng minh còn hoạt động.
• openclaw channels status --probe và openclaw doctor cảnh báo khi một tài khoản polling đang chạy chưa hoàn tất getUpdates sau thời gian gia hạn khởi động, khi một tài khoản webhook đang chạy chưa hoàn tất setWebhook sau thời gian gia hạn khởi động, hoặc khi hoạt động transport polling thành công gần nhất đã cũ.
• Chỉ tăng channels.telegram.pollingStallThresholdMs khi các lệnh gọi getUpdates chạy lâu vẫn khỏe nhưng host của bạn vẫn báo nhầm các lần khởi động lại do polling bị kẹt. Tình trạng kẹt kéo dài thường chỉ ra sự cố proxy, DNS, IPv6 hoặc lưu lượng đi ra TLS giữa host và api.telegram.org.
• Telegram cũng tôn trọng biến môi trường proxy của tiến trình cho transport Bot API, bao gồm HTTP_PROXY, HTTPS_PROXY, ALL_PROXY và các biến chữ thường tương ứng. NO_PROXY / no_proxy vẫn có thể bỏ qua api.telegram.org.
• Nếu proxy do OpenClaw quản lý được cấu hình qua OPENCLAW_PROXY_URL cho môi trường dịch vụ và không có biến môi trường proxy chuẩn nào, Telegram cũng dùng URL đó cho transport Bot API.
• Trên các host VPS có lưu lượng đi ra trực tiếp/TLS không ổn định, định tuyến các lệnh 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 (ngoại trừ WSL2) và dnsResultOrder=ipv4first.
• Nếu host của bạn là WSL2 hoặc rõ ràng hoạt động tốt hơn với hành vi chỉ IPv4, hãy ép chọn family:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Các câu trả lời trong dải benchmark RFC 2544 (198.18.0.0/15) đã được cho phép theo mặc định cho tải xuống media Telegram. Nếu fake-IP đáng tin cậy hoặc proxy trong suốt ghi lại api.telegram.org thành một địa chỉ riêng tư/nội bộ/dùng đặc biệt khác trong khi tải xuống media, bạn có thể chọn bật bypass chỉ dành cho Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Tùy chọn bật tương tự có sẵn theo từng tài khoản tại channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Nếu proxy của bạn phân giải các host media Telegram thành 198.18.x.x, trước tiên hãy để cờ nguy hiểm tắt. Media Telegram đã cho phép dải benchmark RFC 2544 theo mặc định.

• Ghi đè bằng 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