Chuyển đến nội dung chính

​
Telegram (Bot API)

Status: production-ready cho bot DM + nhóm qua grammY. Long polling là chế độ mặc định; webhook là tùy chọn.

Ghép cặp

Chính sách DM mặc định cho Telegram là ghép cặp.

Khắc phục sự cố kênh

Chẩn đoán đa kênh và playbook sửa lỗi.

Cấu hình Gateway

Mẫu cấu hình kênh đầy đủ và ví dụ.

​
Quick setup

1

Tạo bot token trong BotFather

Mở Telegram và chat với @BotFather (xác nhận handle chính xác là @BotFather).Chạy /newbot, làm theo hướng dẫn và lưu lại token.
2

Cấu hình token và chính sách DM

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}
Env fallback: TELEGRAM_BOT_TOKEN=... (chỉ áp dụng cho tài khoản mặc định).
3

Khởi động gateway và phê duyệt DM đầu tiên

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
Mã ghép cặp hết hạn sau 1 giờ.
4

Thêm bot vào nhóm

Thêm bot vào nhóm của bạn, sau đó thiết lập channels.telegram.groups và groupPolicy phù hợp với mô hình truy cập của bạn.
Thứ tự phân giải token có phân biệt theo tài khoản. Trong thực tế, giá trị trong config được ưu tiên hơn env fallback, và TELEGRAM_BOT_TOKEN chỉ áp dụng cho tài khoản mặc định.

​
Telegram side settings

Telegram bots mặc định bật Privacy Mode, giới hạn các tin nhắn nhóm mà bot nhận được.Nếu bot cần thấy tất cả tin nhắn trong nhóm, bạn có thể:
  • tắt privacy mode qua /setprivacy, hoặc
  • đặt bot làm admin của nhóm.
Khi thay đổi privacy mode, hãy xóa + thêm lại bot trong từng nhóm để Telegram áp dụng thay đổi.
Trạng thái admin được thiết lập trong cài đặt nhóm Telegram.Bot là admin sẽ nhận tất cả tin nhắn nhóm, hữu ích cho hành vi luôn bật trong nhóm.
  • /setjoingroups để cho phép/từ chối thêm vào nhóm
  • /setprivacy để điều chỉnh hành vi hiển thị trong nhóm

​
Access control và kích hoạt

channels.telegram.dmPolicy kiểm soát quyền truy cập tin nhắn trực tiếp:
  • pairing (mặc định)
  • allowlist
  • open (yêu cầu allowFrom bao gồm "*")
  • disabled
channels.telegram.allowFrom chấp nhận Telegram user ID dạng số. Tiền tố telegram: / tg: được chấp nhận và chuẩn hóa. Trình hướng dẫn onboarding chấp nhận nhập @username và sẽ phân giải sang ID số. Nếu bạn đã nâng cấp và config chứa các mục allowlist dạng @username, hãy chạy openclaw doctor --fix để phân giải chúng (best-effort; yêu cầu bot token Telegram).

​
Tìm Telegram user ID của bạn

An toàn hơn (không dùng bot bên thứ ba):
  1. DM bot của bạn.
  2. Chạy openclaw logs --follow.
  3. Đọc from.id.
Cách chính thức qua Bot API:
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Cách bên thứ ba (ít riêng tư hơn): @userinfobot hoặc @getidsbot.

​
Runtime behavior

  • Telegram được sở hữu bởi tiến trình gateway.
  • Định tuyến xác định: tin nhắn vào từ Telegram sẽ phản hồi lại Telegram (model không tự chọn kênh).
  • Tin nhắn đến được chuẩn hóa vào phong bì kênh dùng chung với metadata trả lời và placeholder media.
  • Phiên nhóm được tách biệt theo group ID. Forum topics nối thêm :topic:<threadId> để giữ tách biệt.
  • Tin nhắn DM có thể mang message_thread_id; OpenClaw định tuyến bằng session key theo thread và giữ thread ID khi phản hồi.
  • Long polling dùng grammY runner với tuần tự theo từng chat/từng thread. Tổng mức song song dùng agents.defaults.maxConcurrent.
  • Telegram Bot API không hỗ trợ read-receipt (sendReadReceipts không áp dụng).