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

• trò chuyện 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 giữ một bản nháp trạng thái có thể chỉnh sửa cho tiến độ công cụ, xóa nó khi hoàn tất và gửi câu trả lời cuối cùng dưới dạng tin nhắn bình thường
• streaming.preview.toolProgress kiểm soát việc các cập nhật công cụ/tiến độ có dùng lại cùng một tin nhắn xem trước đã chỉnh sửa hay không (mặc định: true khi phát trực tuyến bản xem trước đang hoạt động)
• streaming.preview.commandText kiểm soát chi tiết lệnh/thực thi bên trong các dòng tiến độ công cụ đó: raw (mặc định, giữ nguyên hành vi đã phát hành) hoặc status (chỉ nhãn công cụ)
• các giá trị cũ channels.telegram.streamMode và 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
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

• bản xem trước ngắn trong DM/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ỗ
• các kết quả văn bản dài bị chia thành nhiều tin nhắn Telegram sẽ dùng lại bản xem trước hiện có làm phần kết quả đầu tiên khi có thể, rồi chỉ gửi các phần còn lại
• kết quả ở chế độ tiến độ sẽ xóa bản nháp trạng thái và dùng cơ chế gửi cuối cùng bình thường thay vì chỉnh sửa bản nháp thành câu trả lời
• nếu chỉnh sửa cuối cùng thất bại trước khi văn bản hoàn tất được xác nhận, OpenClaw dùng cơ chế gửi cuối cùng bình thường và dọn dẹp bản xem trước cũ

• /reasoning stream gửi suy luận tới bản xem trước trực tiếp trong khi tạo
• bản xem trước suy luận bị xóa sau khi gửi kết quả cuối cùng; dùng /reasoning on khi suy luận cần tiếp tục hiển thị
• câu trả lời cuối cùng đượ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.
• Các thẻ HTML được Telegram hỗ trợ được giữ nguyên; HTML không được hỗ trợ sẽ được escape.
• 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.

• 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à 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/skill vẫn có thể hoạt động khi được gõ, 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 vượt giới hạn sau khi cắt bớt; hãy giảm lệnh Plugin/skill/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 trực tiếp tới Bot API vẫn hoạt động có thể nghĩa là channels.telegram.apiRoot đã được đặt thành endpoint đầy đủ /bot<TOKEN>. apiRoot phải chỉ là gốc Bot API, và openclaw doctor --fix sẽ xóa phần đuôi /bot<TOKEN> vô tình thêm vào.
• 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 điều này không được báo cáo như 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 đang 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]] phản hồi tin nhắn kích hoạt
• [[reply_to:<id>]] phản hồ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>
• phản hồ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 tin nhắn 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
          }
        }
      }
    }
  }
}

​

Tin nhắn âm thanh

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

{
  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: được tải xuống và xử lý (placeholder <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 nghĩa là chỉ 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 thông qua bộ nhớ đệm tin nhắn đã gửi).
• Sự kiện phản ứng vẫn tuân theo kiểm soát truy cập 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ập nhật phản ứng.
  • nhóm không phải diễn đàn định tuyến đến phiên trò chuyện nhóm
  • nhóm diễn đàn định tuyến đến phiên chủ đề chung của nhóm (:topic:1), không phải đúng chủ đề gốc

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• dự phòng emoji danh tính tác tử (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,
    },
  },
}

• Mặc định của channels.telegram.textChunkLimit là 4000.
• channels.telegram.chunkMode="newline" ưu tiên ranh giới đoạn văn (dòng trống) trước khi chia theo độ 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.mediaGroupFlushMs (mặc định 500) kiểm soát thời gian album/nhóm phương tiện Telegram được đệm trước khi OpenClaw điều phối chúng thành một tin nhắn đến. Tăng giá trị này nếu các phần album đến muộn; giảm để giảm độ trễ phản hồi album.
• channels.telegram.timeoutSeconds ghi đè thời gian chờ của client API Telegram (nếu không đặt, mặc định grammY được áp dụng). Client bot kẹp các giá trị được cấu hình thấp hơn guard yêu cầu văn bản/đang nhập chiều đi 60 giây để grammY không hủy giao hàng phản hồi hiển thị trước khi guard vận chuyển và dự phòng của OpenClaw có thể chạy. Long polling vẫn dùng guard yêu cầu getUpdates 45 giây để các lượt polling nhàn rỗi không bị bỏ mặc vô thời hạn.
• channels.telegram.pollingStallThresholdMs mặc định là 120000; chỉ tinh chỉnh trong khoảng 30000 đến 600000 cho các lần khởi động lại do polling bị kẹt 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 trả lời/trích dẫn/chuyển tiếp được chuẩn hóa vào một cửa sổ ngữ cảnh hội thoại được chọn khi Gateway đã quan sát các tin nhắn cha; bộ nhớ đệm tin nhắn đã quan sát được lưu bền vững bên cạnh kho phiên. Telegram chỉ bao gồm một reply_to_message nông trong cập nhật, nên các chuỗi cũ hơn bộ nhớ đệm bị giới hạn bởi payload cập nhật hiện tại của Telegram.
• allowlist Telegram chủ yếu kiểm soát ai có thể kích hoạt tác tử, không phải là ranh giới biên tập 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 chiều đi có thể khôi phục. Giao hàng phản hồi cuối cùng cho tin nhắn đến cũng dùng cơ chế thử lại gửi an toàn có giới hạn cho lỗi trước khi kết nối Telegram, nhưng không thử lại các phong bì mạng mơ hồ 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 send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

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 cuộc trò chuyện đó
• --force-document để gửi hình ảnh, GIF và video chiều đi dưới dạng tài liệu thay vì tải lên dưới dạng ảnh nén, phương tiện động, hoặc video

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

• channels.telegram.execApprovals.enabled (tự động bật khi ít nhất một người phê duyệt có thể phân giải được)
• channels.telegram.execApprovals.approvers (dự phòng sang 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ế độ quyền riêng tư của Telegram phải cho phép hiển thị đầy đủ.
  • BotFather: /setprivacy -> Disable
  • sau đó xóa + 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 tê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 tư cách thành viên.
• kiểm tra phiên nhanh: /activation always.

• khi có channels.telegram.groups, 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 đô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 nghĩa là menu gốc có quá nhiều mục; giảm lệnh plugin/skill/tùy chỉnh hoặc tắt menu gốc
• Các lệnh khởi động deleteMyCommands / setMyCommands và các lệnh nhập trạng thái sendChatAction đều có giới hạn thời gian và thử lại một lần qua phương án dự phòng truyền tải 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 đề khả dụng DNS/HTTPS tới api.telegram.org

• getMe returned 401 là lỗi xác thực Telegram cho 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; coi nó như “không có webhook tồn tại” chỉ trì hoãn cùng lỗi token sai đó sang các lệnh gọi API sau.

• 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 kiểu AbortSignal không khớp.
• Một số máy chủ phân giải api.telegram.org sang IPv6 trước; egress IPv6 bị lỗi 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 các lỗi này như lỗi mạng có thể khôi phục.
• Trong lúc khởi động polling, OpenClaw tái sử dụng probe getMe khởi động thành công cho grammY để runner không cần một getMe thứ hai trước getUpdates đầu tiên.
• Nếu deleteWebhook thất bại với lỗi mạng tạm thời trong lúc khởi động polling, OpenClaw tiếp tục vào long polling thay vì thực hiện một lệnh gọi control-plane trước polling khác. Webhook vẫn còn hoạt động sẽ xuất hiện dưới dạng xung đột getUpdates; khi đó OpenClaw dựng lại truyền tải Telegram và thử lại dọn dẹp webhook.
• Nếu socket Telegram được tái tạo theo một chu kỳ cố định ngắn, hãy kiểm tra channels.telegram.timeoutSeconds thấp; bot client kẹp các giá trị đã cấu hình thấp hơn các bộ bảo vệ yêu cầu outbound và getUpdates, nhưng các bản phát hành cũ hơn có thể hủy mọi lượt polling hoặc trả lời khi giá trị này thấp hơn các bộ bảo vệ đó.
• Nếu nhật ký bao gồm Polling stall detected, OpenClaw khởi động lại polling và dựng lại truyền tải Telegram sau 120 giây không có liveness long-poll hoàn tất theo mặc định.
• 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 truyền tải 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 mạnh nhưng máy chủ của bạn vẫn báo nhầm các lần khởi động lại do polling-stall. Tình trạng stall kéo dài thường chỉ ra vấn đề proxy, DNS, IPv6 hoặc TLS egress giữa máy chủ và api.telegram.org.
• Telegram cũng tôn trọng env proxy của tiến trình cho truyền tải 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ó env proxy tiêu chuẩn, Telegram cũng dùng URL đó cho truyền tải Bot API.
• Trên máy chủ VPS có egress/TLS trực tiếp 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 (trừ WSL2). Thứ tự kết quả DNS của Telegram tôn trọng OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, sau đó channels.telegram.network.dnsResultOrder, sau đó mặc định của tiến trình như NODE_OPTIONS=--dns-result-order=ipv4first; nếu không áp dụng mục nào, Node 22+ quay về ipv4first.
• Nếu máy chủ 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 buộc chọn family:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Câu trả lời dải benchmark RFC 2544 (198.18.0.0/15) đã được cho phép cho tải xuống media Telegram theo mặc định. Nếu một 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 lúc tải xuống media, bạn có thể chọn tham gia cơ chế bỏ qua chỉ dành cho Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Tùy chọn tham gia 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 máy chủ 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 đè 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