Telegram

Bot Telegram mặc định dùng Privacy Mode, giới hạn những 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 xóa rồi 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 kiểm soát trong cài đặt nhóm Telegram.

Bot quản trị viên nhận tất cả tin nhắn nhóm, hữu ích cho hành vi nhóm luôn hoạt động.

• /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 một phần theo thời gian thực:

• chat trực tiếp: tin nhắn xem trước + editMessageText
• nhóm/topic: 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 trình 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ập nhật công cụ/tiến trình 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 hoạt động)
• streaming.preview.commandText kiểm soát chi tiết command/exec bên trong các dòng tiến trình 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ụ)
• channels.telegram.streamMode cũ và giá trị boolean streaming được phát hiện; chạy openclaw doctor --fix để di chuyển chúng sang channels.telegram.streaming.mode

Cập nhật xem trước tiến trình công cụ là các dòng trạng thái ngắn hiển thị trong khi công cụ chạy, ví dụ thực thi lệnh, đọc tệp, cập nhật kế hoạch, hoặc tóm tắt patch. Telegram bật mặc định các dòng này để khớp với hành vi OpenClaw đã phát hành từ v2026.4.22 trở về sau. Để giữ phầ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 trình công cụ, hãy đặt:

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

Để giữ tiến trình công cụ hiển thị nhưng ẩn văn bản command/exec, hãy đặt:

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

Dùng chế độ progress khi bạn muốn hiển thị tiến trình công cụ mà không chỉnh sửa câu trả lời cuối cùng vào cùng 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 của Telegram bị tắt và đoạn trò chuyện chung về công cụ/tiến trình 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, tải trọng phương tiện và lỗi vẫn được định tuyến qua cơ chế gửi kết quả cuối cùng thông 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 trình công cụ.

Đối với trả lờ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ỗ
• kết quả văn bản dài phải tách thành nhiều tin nhắn Telegram sẽ tái sử dụng 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ế độ tiến trình xóa bản nháp trạng thái và dùng cơ chế gửi kết quả cuối cùng thông 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 kết quả cuối cùng thông thường và dọn dẹp bản xem trước cũ

Đối với trả lời phức tạp (ví dụ tải trọng phương tiện), OpenClaw quay về cơ chế gửi kết quả cuối cùng thông 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 khối. Khi phát trực tuyến khối được bật rõ ràng cho Telegram, OpenClaw bỏ qua luồng 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 đang 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 đi 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.
• HTML thô từ mô hình được thoát để giảm lỗi phân tích cú pháp 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.

Bản xem trước liên kết được bật theo 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ý khi 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ự 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

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.

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; 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 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 nằm ở cuối.
• getMe returned 401 nghĩa là Telegram đã từ chối mã thông báo bot đã cấu hình. Cập nhật botToken, tokenFile hoặc TELEGRAM_BOT_TOKEN bằng mã thông báo 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 là lỗi dọn dẹp Webhook.
• setMyCommands failed với lỗi mạng/fetch thường nghĩa là DNS/HTTPS đi ra tới api.telegram.org 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 mã thông báo bootstrap tồn tại trong thời gian ngắn. Chuyển giao bootstrap tích hợp giữ mã thông báo nút chính ở scopes: []; mọi mã thông báo operator đượ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ò, nên danh sách cho phép operator đó chỉ đáp ứng các yêu cầu operator; vai trò không phải operator vẫn cần phạm vi dưới tiền tố vai trò riêng của chúng.

Nếu 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 đó 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ừng 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ượt nhấp 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:

• 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 theo mặc định và không có nút bật/tắt channels.telegram.actions.* riêng. Việc gửi khi chạy dùng snapshot cấu hình/bí mật đang hoạt động (khởi động/tải lại), nên 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 xóa phản ứng: /tools/reactions

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

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

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

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

Khi phân luồng trả lời được bật và văn bản hoặc chú thích Telegram gốc có sẵn, OpenClaw tự động đưa vào 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, nên các tin nhắn dài hơn được trích dẫn từ đầu và quay về trả lời thuần nếu Telegram từ chối trích dẫn.

Lưu ý: off tắt phân luồng trả lờ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ủ đề nối thêm :topic:<threadId>
• 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>

Trường hợp đặc biệt của 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 từng 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
          }
        }
      }
    }
  }
}

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

Liên kết chủ đề ACP bền vững: 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ỉ áp dụng cho chủ đề diễn đàn trong nhóm/siêu nhóm. Xem Agent ACP.

Sinh ACP gắn với luồng từ chat: /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 tiếp theo được định tuyến trực tiếp tới đó. 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 giữ định tuyến DM và siêu dữ liệu trả lời trên các phiên phẳng theo mặc định; 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ới tệp âm thanh.

• mặc định: hành vi tệp âm thanh
• thẻ [[audio_as_voice]] trong phản hồi của agent để buộc gửi 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 agent; phát hiện lượt nhắc vẫn dùng bản chép lời thô nên các tin nhắn thoại bị chặn bằng lượt nhắc 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ới 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ý (phần giữ chỗ <media:sticker>)
• TGS động: bị bỏ qua
• WEBM video: bị bỏ qua

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 bản 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 vào hàng đợi như:

• 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 qua bộ nhớ đệm tin nhắn đã gửi).
• Sự kiện phản ứng vẫn tuân thủ 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 bản 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 chủ đề khởi tạo chính xá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
• emoji dự phòng của danh tính agent (agents.list[].identity.emoji, nếu không có 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ần 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).

Trong chế độ long-polling, OpenClaw chỉ lưu watermark khởi động lại sau khi một bản cập nhật được dispatch thành công. Nếu một handler thất bại, bản 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 cho việc khử trùng lặp khi khởi động lại.

Listener cục bộ liên kết tới 127.0.0.1:8787. Đối với ingress 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 của 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ý bản cập nhật bất đồng bộ qua cùng các lane bot theo từng cuộc trò chuyện/từng chủ đề được dùng bởi long polling, nên các lượt agent chậm không giữ ACK giao hàng của Telegram.

• 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 phương tiện Telegram đến và đi.
• channels.telegram.mediaGroupFlushMs (mặc định 500) kiểm soát thời gian các album/nhóm phương tiện Telegram được đệm trước khi OpenClaw dispatch 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á trị này để giảm độ trễ trả lời album.
• channels.telegram.timeoutSeconds ghi đè thời gian chờ của client Telegram API (nếu không đặt, mặc định grammY được áp dụng). Bot client kẹp các giá trị cấu hình thấp hơn guard 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 guard truyền tải 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 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 trả lời/trích dẫn/chuyển tiếp hiện được chuyển tiếp như đã nhận.
• allowlist Telegram chủ yếu kiểm soát ai có thể kích hoạt agent, không phải 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/tools/actions) đối với lỗi API gửi đi có thể phục hồi. Việc gửi phản hồi cuối cùng cho tin nhắn đến cũng dùng một lần thử lại safe-send 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 envelope mạng mơ hồ sau khi gửi có thể nhân đôi tin nhắn hiển thị.

Mục tiêu gửi của CLI và message-tool có thể là ID trò chuyện dạng 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"

Telegram poll 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ờ 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 ảnh và GIF đi dưới dạng tài liệu thay vì tải lên ảnh nén hoặc phương tiện động

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

• 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

Telegram hỗ trợ phê duyệt exec trong DM của người phê duyệt và có thể tùy chọn đăng prompt trong cuộc trò chuyện hoặc chủ đề khởi tạo. 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 có thể phân giải í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

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. Lần ghép cặp DM được phê duyệt đầu tiên bootstrap commands.ownerAllowFrom khi chưa có chủ sở hữu lệnh nào, 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 qua 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 prompt đến một chủ đề diễn đàn, OpenClaw giữ nguyên chủ đề cho prompt phê duyệt và phần tiếp theo. 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 mục tiêu (dm, group, hoặc all). ID phê duyệt có tiền tố plugin: được phân giải qua phê duyệt plugin; các ID khác đượ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 -> Tắt
  • sau đó xóa bot khỏi nhóm và thêm lại
• 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ố tường minh; 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ố)
• quyền lệnh vẫn được á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/Skills/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 báo đang nhập sendChatAction được giới hạn thời gian và thử lại một lần qua cơ chế 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 sự cố DNS/khả năng truy cập 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; coi nó là no webhook exists sẽ chỉ trì hoãn cùng lỗi token sai đó sang các lệnh gọi API sau.

• Node 22+ cùng 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 Telegram API gián đoạn.
• Nếu nhật ký có 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 lần kiểm tra getMe khởi động thành công cho grammY để trình chạy không cần getMe lần 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 thêm một lệnh gọi control-plane trước polling. Webhook vẫn còn hoạt động sẽ xuất hiện dưới dạng xung đột getUpdates; sau đó OpenClaw dựng lại truyền tải Telegram và thử lại việc dọn dẹp webhook.
• Nếu socket Telegram được tái tạo theo chu kỳ cố định ngắn, hãy kiểm tra channels.telegram.timeoutSeconds thấp; máy khách bot chặn các giá trị cấu hình thấp hơn các ngưỡng bảo vệ yêu cầu đi ra và getUpdates, nhưng các bản phát hành cũ 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 ngưỡng đó.
• Nếu nhật ký có 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ó long-poll liveness 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 khoảng 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 khoảng 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 khởi động lại do polling-stall giả. Tình trạng kẹt kéo dài thường chỉ ra sự cố proxy, DNS, IPv6, hoặc đường ra TLS giữa máy chủ và api.telegram.org.
• Telegram cũng tuân theo biến môi trường 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ó biến môi trường proxy chuẩn nào, Telegram cũng dùng URL đó cho truyền tải Bot API.
• Trên máy chủ VPS có đường ra/TLS trực tiếp không ổn định, định tuyến các lệnh gọi Telegram API 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 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ó mục nào áp dụng, Node 22+ quay về 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, hãy buộc 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 theo mặc định cho tải xuống phương tiện 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 cho mục đích đặc biệt khác trong lúc tải xuống phương tiện, bạn có thể bật bỏ qua 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 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 đè 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