Telegram

Bot Telegram mặc định dùng Privacy Mode, chế độ này giới hạn các tin nhắn nhóm mà chúng nhận được.

Nếu bot phải thấy tất cả tin nhắn nhóm, hãy:

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

Khi bật/tắt chế độ riêng tư, hãy gỡ + thêm lại bot trong từng nhóm để Telegram áp dụng thay đổi.

Trạng thái quản trị viên được điều khiển trong cài đặt nhóm Telegram.

Bot quản trị viên nhận tất cả tin nhắn nhóm, điều này hữu ích cho hành vi nhóm luôn bật.

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

OpenClaw có thể stream phản hồi từng phần theo thời gian thực:

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

Yêu cầu:

• 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

Các cập nhật bản xem trước tiến độ công cụ là những dòng trạng thái ngắn hiển thị trong khi công cụ chạy, ví dụ như thực thi lệnh, đọc tệp, cập nhật kế hoạch hoặc tóm tắt bản vá. Telegram bật mặc định các cập nhật này để khớp với hành vi OpenClaw đã phát hành từ v2026.4.22 trở đi. Để giữ bản xem trước đã chỉnh sửa cho văn bản câu trả lời nhưng ẩn các dòng tiến độ công cụ, hãy đặt:

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

Để giữ tiến độ công cụ hiển thị nhưng ẩn văn bản lệnh/thực thi, hãy đặt:

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

Dùng chế độ progress khi bạn muốn tiến độ công cụ hiển thị mà không chỉnh sửa câu trả lời cuối cùng vào chính tin nhắn đó. Đặt chính sách văn bản lệnh dưới streaming.progress:

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

Chỉ dùng streaming.mode: "off" khi bạn muốn chỉ gửi kết quả cuối cùng: các chỉnh sửa bản xem trước Telegram bị tắt và phần trao đổi chung về công cụ/tiến độ bị chặn thay vì được gửi dưới dạng tin nhắn trạng thái độc lập. Lời nhắc phê duyệt, payload phương tiện và lỗi vẫn được định tuyến qua cơ chế gửi cuối cùng bình thường. Dùng streaming.preview.toolProgress: false khi bạn chỉ muốn giữ các chỉnh sửa bản xem trước câu trả lời trong khi ẩn các dòng trạng thái tiến độ công cụ.

Đối với phản hồi chỉ có văn bản:

• 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ũ

Đối với phản hồi phức tạp (ví dụ payload phương tiện), OpenClaw chuyển về cơ chế gửi cuối cùng bình thường rồi dọn dẹp tin nhắn xem trước.

Phát trực tuyến bản xem trước tách biệt với phát trực tuyến theo khối. Khi phát trực tuyến theo khối được bật rõ ràng cho Telegram, OpenClaw bỏ qua luồng bản xem trước để tránh phát trực tuyến hai lần.

Luồng suy luận chỉ dành cho Telegram:

• /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 gửi ra dùng Telegram parse_mode: "HTML".

• 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.

Bản xem trước liên kết được bật mặc định và có thể tắt bằng channels.telegram.linkPreview: false.

Việc đăng ký menu lệnh Telegram được xử lý lúc khởi động bằng setMyCommands.

Mặc định lệnh gốc:

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

Thêm mục menu lệnh tùy chỉnh:

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

Quy tắc:

• 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

Ghi chú:

• 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

Nếu lệnh gốc bị tắt, các lệnh tích hợp sẽ bị xóa. Lệnh tùy chỉnh/Plugin vẫn có thể đăng ký nếu được cấu hình.

Các lỗi thiết lập thường gặp:

• 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)

Khi Plugin device-pair được cài đặt:

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

Mã thiết lập mang một token bootstrap ngắn hạn. Chuyển giao bootstrap tích hợp giữ token nút chính ở scopes: []; mọi token người vận hành được chuyển giao vẫn bị giới hạn trong operator.approvals, operator.read, operator.talk.secrets và operator.write. Kiểm tra phạm vi bootstrap có tiền tố vai trò, vì vậy danh sách cho phép người vận hành đó chỉ thỏa mãn yêu cầu của người vận hành; các vai trò không phải người vận hành vẫn cần phạm vi dưới tiền tố vai trò riêng của chúng.

Nếu một thiết bị thử lại với chi tiết xác thực đã thay đổi (ví dụ vai trò/phạm vi/khóa công khai), yêu cầu đang chờ trước đó sẽ bị thay thế và yêu cầu mới dùng một requestId khác. Chạy lại /pair pending trước khi phê duyệt.

Chi tiết thêm: Ghép nối.

Cấu hình phạm vi bàn phím nội tuyến:

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

Ghi đè theo tài khoản:

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

Phạm vi:

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

capabilities: ["inlineButtons"] cũ ánh xạ tới inlineButtons: "all".

Ví dụ hành động tin nhắn:

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

Các lần bấm callback được chuyển cho agent dưới dạng văn bản: callback_data: <value>

Hành động công cụ Telegram bao gồm:

• 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)

Hành động tin nhắn kênh cung cấp các bí danh tiện dụng (send, react, delete, edit, sticker, sticker-search, topic-create).

Điều khiển cổng kiểm soát:

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

Lưu ý: edit và topic-create hiện được bật mặc định và không có công tắc channels.telegram.actions.* riêng. Các lần gửi runtime dùng ảnh chụp nhanh cấu hình/bí mật đang hoạt động (khởi động/tải lại), vì vậy các đường dẫn hành động không thực hiện phân giải lại SecretRef tùy biến cho từng lần gửi.

Ngữ nghĩa gỡ phản ứng: /tools/reactions

Telegram hỗ trợ các thẻ luồng phản hồi rõ ràng trong đầu ra được tạo:

• [[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ể

channels.telegram.replyToMode kiểm soát cách xử lý:

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

Khi luồng phản hồi được bật và văn bản hoặc chú thích Telegram gốc có sẵn, OpenClaw tự động bao gồm một đoạn trích dẫn Telegram gốc. Telegram giới hạn văn bản trích dẫn gốc ở 1024 đơn vị mã UTF-16, vì vậy các tin nhắn dài hơn được trích dẫn từ phần đầu và chuyển về phản hồi thuần nếu Telegram từ chối trích dẫn.

Lưu ý: off tắt luồng phản hồi ngầm định. Các thẻ [[reply_to_*]] rõ ràng vẫn được tôn trọng.

Siêu nhóm diễn đàn:

• 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>

Trường hợp đặc biệt chủ đề chung (threadId=1):

• 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

Kế thừa chủ đề: mục chủ đề kế thừa cài đặt nhóm trừ khi bị ghi đè (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId chỉ thuộc chủ đề và không kế thừa từ mặc định nhóm.

Định tuyến agent theo chủ đề: Mỗi chủ đề có thể định tuyến tới một agent khác bằng cách đặt agentId trong cấu hình chủ đề. Điều này cung cấp cho mỗi chủ đề workspace, bộ nhớ và phiên riêng biệt. Ví dụ:

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

Mỗi chủ đề sau đó có khóa phiên riêng: agent:zu:telegram:group:-1001234567890:topic:3

Liên kết chủ đề ACP bền vững: Các chủ đề diễn đàn có thể ghim phiên harness ACP thông qua các liên kết ACP có kiểu ở cấp cao nhất (bindings[] với type: "acp" và match.channel: "telegram", peer.kind: "group", cùng một id đủ điều kiện theo chủ đề như -1001234567890:topic:42). Hiện chỉ giới hạn cho các chủ đề diễn đàn trong nhóm/siêu nhóm. Xem Tác tử ACP.

Sinh ACP gắn với luồng từ cuộc trò chuyện: /acp spawn <agent> --thread here|auto liên kết chủ đề hiện tại với một phiên ACP mới; các lượt theo dõi sẽ được định tuyến trực tiếp đến đó. OpenClaw ghim xác nhận sinh trong chủ đề. Yêu cầu channels.telegram.threadBindings.spawnSessions vẫn được bật (mặc định: true).

Ngữ cảnh mẫu hiển thị MessageThreadId và IsForum. Các cuộc trò chuyện DM có message_thread_id mặc định vẫn giữ định tuyến DM và siêu dữ liệu trả lời trên phiên phẳng; chúng chỉ dùng khóa phiên nhận biết luồng khi được cấu hình với threadReplies: "inbound", threadReplies: "always", requireTopic: true, hoặc một cấu hình chủ đề khớp. Dùng channels.telegram.dm.threadReplies ở cấp cao nhất cho mặc định của tài khoản, hoặc direct.<chatId>.threadReplies cho một DM.

Tin nhắn âm thanh

Telegram phân biệt ghi chú thoại và tệp â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.

Ví dụ hành động tin nhắn:

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

Tin nhắn video

Telegram phân biệt tệp video và ghi chú video.

Ví dụ hành động tin nhắn:

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

Ghi chú video không hỗ trợ chú thích; văn bản tin nhắn được cung cấp sẽ được gửi riêng.

Nhãn dán

Xử lý nhãn dán đến:

• WEBP tĩnh: được tải xuống và xử lý (placeholder <media:sticker>)
• TGS động: bỏ qua
• WEBM video: bỏ qua

Các trường ngữ cảnh nhãn dán:

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

Tệp bộ nhớ đệm nhãn dán:

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

Nhãn dán được mô tả một lần (khi có thể) và được lưu vào bộ nhớ đệm để giảm các lần gọi thị giác lặp lại.

Bật hành động nhãn dán:

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

Hành động gửi nhãn dán:

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

Tìm kiếm nhãn dán đã lưu trong bộ nhớ đệm:

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

Phản ứng Telegram đến dưới dạng cập nhật message_reaction (tách biệt với payload tin nhắn).

Khi được bật, OpenClaw đưa các sự kiện hệ thống như sau vào hàng đợi:

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

Cấu hình:

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

Ghi chú:

• 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

allowed_updates cho polling/webhook tự động bao gồm message_reaction.

ackReaction gửi một emoji xác nhận trong khi OpenClaw đang xử lý một tin nhắn đến.

Thứ tự phân giải:

• 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ì "👀")

Ghi chú:

• 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.

Ghi cấu hình kênh được bật theo mặc định (configWrites !== false).

Các lượt ghi do Telegram kích hoạt bao gồm:

• 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)

Tắt:

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

Mặc định là long polling. Đối với chế độ webhook, đặt channels.telegram.webhookUrl và channels.telegram.webhookSecret; tùy chọn webhookPath, webhookHost, webhookPort (mặc định /telegram-webhook, 127.0.0.1, 8787).

Ở chế độ long-polling, OpenClaw chỉ lưu watermark khởi động lại sau khi một cập nhật được điều phối thành công. Nếu một handler thất bại, cập nhật đó vẫn có thể được thử lại trong cùng tiến trình và không được ghi là đã hoàn tất để khử trùng lặp khi khởi động lại.

Bộ lắng nghe cục bộ liên kết với 127.0.0.1:8787. Đối với lưu lượng vào công khai, hãy đặt reverse proxy phía trước cổng cục bộ hoặc chủ ý đặt webhookHost: "0.0.0.0".

Chế độ webhook xác thực các guard yêu cầu, token bí mật Telegram và thân JSON trước khi trả về 200 cho Telegram. Sau đó OpenClaw xử lý cập nhật bất đồng bộ qua cùng các làn bot theo từng cuộc trò chuyện/từng chủ đề được long polling sử dụng, nên các lượt tác tử chậm không giữ ACK giao hàng của Telegram.

• 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ị.

Mục tiêu gửi của CLI và công cụ tin nhắn có thể là ID trò chuyện số, username, hoặc mục tiêu chủ đề diễn đàn:

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"

Poll Telegram dùng openclaw message poll và hỗ trợ chủ đề diễn đàn:

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

Các cờ poll chỉ dành cho Telegram:

• --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:)

Gửi Telegram cũng hỗ trợ:

• --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

Kiểm soát hành động:

• 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

Telegram hỗ trợ phê duyệt exec trong DM của người phê duyệt và có thể tùy chọn đăng lời nhắc trong cuộc trò chuyện hoặc chủ đề gốc. Người phê duyệt phải là ID người dùng Telegram dạng số.

Đường dẫn cấu hình:

• 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

channels.telegram.allowFrom, groupAllowFrom, và defaultTo kiểm soát ai có thể nói chuyện với bot và bot gửi phản hồi thông thường ở đâu. Chúng không biến ai đó thành người phê duyệt exec. Cặp DM được phê duyệt đầu tiên khởi tạo commands.ownerAllowFrom khi chưa có chủ sở hữu lệnh, nên thiết lập một chủ sở hữu vẫn hoạt động mà không cần lặp ID trong execApprovals.approvers.

Giao hàng kênh hiển thị văn bản lệnh trong cuộc trò chuyện; chỉ bật channel hoặc both trong các nhóm/chủ đề đáng tin cậy. Khi lời nhắc đến một chủ đề diễn đàn, OpenClaw giữ nguyên chủ đề cho lời nhắc phê duyệt và lượt theo dõi. Phê duyệt exec hết hạn sau 30 phút theo mặc định.

Nút phê duyệt inline cũng yêu cầu channels.telegram.capabilities.inlineButtons cho phép bề mặt đích (dm, group, hoặc all). ID phê duyệt có tiền tố plugin: phân giải qua phê duyệt plugin; các ID khác phân giải qua phê duyệt exec trước.

Xem Phê duyệt exec.

• 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 Adig +short api.telegram.org AAAA