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 việc 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)
• các bản xem trước câu trả lời ban đầu ngắn được debounce, rồi được hiện thực hóa sau một độ trễ có giới hạn nếu lượt chạy vẫn đang hoạt động
• progress giữ một bản nháp trạng thái có thể chỉnh sửa cho tiến độ công cụ, hiển thị nhãn trạng thái ổn định khi hoạt động trả lời đến trước 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 như một tin nhắn bình thường
• streaming.preview.toolProgress kiểm soát liệu các cập nhật công cụ/tiến độ có dùng lại cùng tin nhắn xem trước đã chỉnh sửa hay không (mặc định: true khi preview streaming đ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ụ)
• streaming.progress.commentary (mặc định: false) bật nhận văn bản bình luận/lời dẫn của trợ lý trong bản nháp tiến độ tạm thời
• channels.telegram.streamMode cũ, giá trị boolean streaming, và các khóa xem trước bản nháp native đã nghỉ hưu sẽ được phát hiện; chạy openclaw doctor --fix để di chuyển chúng sang cấu hình streaming hiện tại

{
  "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 tin nhắn xem trước và thực hiện chỉnh sửa cuối cùng tại chỗ
• kết quả văn bản dài bị tách thành nhiều tin nhắn Telegram sẽ dùng lại bản xem trước hiện có làm đoạn cuối cùng đầu tiên khi có thể, rồi chỉ gửi các đoạn còn lại
• kết quả cuối cùng ở chế độ progress xóa bản nháp trạng thái và dùng đường 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 đường gửi cuối cùng bình thường và dọn bản xem trước cũ

• /reasoning stream dùng đường xem trước suy luận của kênh được hỗ trợ; trên Telegram, nó stream phần suy luận vào 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 phần suy luận cần vẫn 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

{
  channels: {
    telegram: {
      richMessages: true,
    },
  },
}

• Agent được thông báo rằng tin nhắn rich của Telegram có sẵn cho bot/tài khoản này.
• Văn bản Markdown được kết xuất qua Markdown IR của OpenClaw và gửi dưới dạng HTML rich của Telegram.
• Payload HTML rich rõ ràng giữ lại các thẻ Bot API 10.1 được hỗ trợ như tiêu đề, bảng, chi tiết, phương tiện rich, và công thức.
• Chú thích phương tiện vẫn dùng chú thích HTML của Telegram vì tin nhắn rich không thay thế chú thích.

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

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

• tên được chuẩn hóa (loại 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 native
• 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/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 bị tràn sau khi cắt bớt; 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 lệnh curl Bot API trực tiếp 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 xóa phần /bot<TOKEN> vô tình ở cuối.
• getMe returned 401 nghĩa là Telegram đã từ chối token bot được 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 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 đến api.telegram.org bị chặn.

​

Lệnh ghép đô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" }],
  ],
}

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Open app:",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}

• sendMessage (to, content, mediaUrl tùy chọn, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content hoặc caption, các nút nội tuyến presentation tùy chọn; chỉnh sửa chỉ nút sẽ cập nhật đánh dấu trả lời)
• createForumTopic (chatId, name, iconColor tùy chọn, 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ủ đề nối thêm :topic:<threadId>
• trả lời và nhập liệu 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 nhập liệu 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 của 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 đầu 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 tác tử; phát hiện nhắc tên vẫn dùng bản chép lời thô nên các tin nhắn thoại có cổng chặn theo nhắc tê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ý (phần giữ chỗ <media:sticker>)
• TGS động: bỏ qua
• WEBM video: bỏ qua

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

{
  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 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 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 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 chủ đề khởi nguồn chính xác

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• phương án dự phòng emoji danh tính tác nhân (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 gửi đến và gửi đ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 gửi chúng dưới dạng một tin nhắn gửi đến. Tăng giá trị này nếu các phần của album đến muộn; giảm giá trị này để giảm độ trễ phản hồi album.
• channels.telegram.timeoutSeconds ghi đè thời gian chờ của client Telegram API (nếu chưa đặt, áp dụng mặc định của grammY). Bot client kẹp các giá trị đã cấu hình thấp hơn mức bảo vệ yêu cầu văn bản/typing gửi đi 60 giây để grammY không hủy việc gửi phản hồi hiển thị trước khi bộ bảo vệ transport và fallback của OpenClaw có thể chạy. Long polling vẫn dùng bộ bảo vệ yêu cầu getUpdates 45 giây để các lượt poll 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-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 được chuẩn hóa vào một cửa sổ ngữ cảnh hội thoại đã chọn khi gateway đã quan sát các tin nhắn cha; cache tin nhắn đã quan sát nằm trong trạng thái Plugin SQLite của OpenClaw, và openclaw doctor --fix nhập các sidecar cũ. Telegram chỉ bao gồm một reply_to_message nông trong các bản cập nhật, nên các chuỗi cũ hơn cache bị giới hạn bởi payload cập nhật hiện tại của Telegram.
• allowlist của 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 toàn bộ ngữ cảnh bổ sung.
• Đ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ể khôi phục. Việc gửi phản hồi cuối cùng đến từ bên ngoài cũng dùng cơ chế thử lại safe-send có giới hạn cho các lỗi Telegram trước khi kết nối, 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 đích :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 gửi kèm ghim khi bot có thể ghim trong chat đó
• --force-document để gửi hình ảnh, GIF và video gửi đ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 gửi đi, bao gồm poll
• channels.telegram.actions.poll=false tắt việc 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 (fallback 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 đó xóa rồi thêm lại bot vào nhóm
• openclaw channels status cảnh báo khi cấu hình kỳ vọng 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 channels.telegram.groups tồn tại, nhóm phải được liệt kê (hoặc bao gồm "*")
• xác minh bot là thành viên trong nhóm
• xem lại nhật ký: openclaw logs --follow để biết lý do bỏ qua

• cấp quyền cho 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 nghĩa là menu gốc có quá nhiều mục; hãy 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 và lệnh nhập sendChatAction được giới hạn và thử lại một lần thông qua cơ chế dự phòng vận chuyển 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 đề về khả năng truy cập 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 khi khởi động cũng là lỗi xác thực; coi nó như “không tồn tại webhook” sẽ chỉ trì hoãn cùng lỗi token sai đó tới các lệnh gọi API sau này.

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

channels:
  telegram:
    network:
      autoSelectFamily: false

• Các câu trả lời thuộc dải benchmark RFC 2544 (198.18.0.0/15) đã được cho phép mặc định cho tải xuống phương tiện Telegram. 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ỉ private/internal/special-use khác trong lúc tải xuống phương tiện, 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ủ phương tiện Telegram thành 198.18.x.x, trước tiên hãy để cờ nguy hiểm tắt. Phương tiện 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