onmay
Blog

Kết nối OpenClaw với Telegram bot: chat với agent từ điện thoại

Agent chạy 24/7 trên VPS sẽ hữu ích hơn nhiều khi bạn nhắn được cho nó ngay trên điện thoại, thay vì phải mở laptop và dashboard. Telegram là kênh nhanh nhất để làm việc này với OpenClaw: chỉ cần một bot token, không cần số điện thoại riêng hay duyệt ứng dụng. Bài này hướng dẫn từ lúc tạo bot đến lúc chat được trong tin nhắn riêng và trong group, theo tài liệu chính thức của OpenClaw.

Luồng kết nối OpenClaw với Telegram: tạo bot ở BotFather, thêm token vào OpenClaw, nhắn bot, duyệt mã pairing, bắt đầu chat

Trước khi bắt đầu

Bạn cần một OpenClaw đang chạy với gateway đã bật. Nếu chưa có, làm theo bài cài OpenClaw trên VPS Ubuntu trước. Kiểm tra nhanh:

openclaw gateway status

Bạn cũng cần tài khoản Telegram trên điện thoại hoặc máy tính.

Bước 1: Tạo bot bằng BotFather

BotFather là bot chính thức của Telegram dùng để tạo và quản lý bot.

  1. Mở Telegram, tìm @BotFather và bấm Start.
  2. Gửi lệnh /newbot.
  3. Đặt tên hiển thị cho bot (ví dụ: "Trợ lý của Minh").
  4. Đặt username, bắt buộc kết thúc bằng bot (ví dụ: minh_assistant_bot).

BotFather trả về một bot token dạng 123456789:AA.... Ai có token này đều điều khiển được bot, nên đừng dán nó vào group chat, ảnh chụp màn hình hay repo Git.

Bước 2: Thêm token vào OpenClaw

Cách nhanh nhất là dùng lệnh channels add trên VPS:

openclaw channels add --channel telegram --token <bot-token>

Nếu muốn sửa cấu hình bằng tay, thêm phần Telegram vào file ~/.openclaw/openclaw.json:

{
  channels: {
    telegram: {
      botToken: "123456789:AA...",
      dmPolicy: "pairing",
    },
  },
}

Ý nghĩa hai dòng cấu hình:

  • botToken: token lấy từ BotFather.
  • dmPolicy: "pairing": người lạ nhắn bot sẽ phải được bạn duyệt trước. Đây là mặc định của OpenClaw cho Telegram.

Gateway đang chạy sẽ tự nạp lại cấu hình kênh, bạn không cần khởi động lại. Kiểm tra kết nối:

openclaw channels status --probe

Bước 3: Duyệt tin nhắn đầu tiên (pairing)

Mở Telegram, tìm username của bot và gửi một tin nhắn bất kỳ. Bot sẽ chưa trả lời ngay, vì tin nhắn này tạo ra một yêu cầu pairing. Trên VPS, xem và duyệt yêu cầu:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Mã pairing hết hạn sau 1 giờ. Nếu quá hạn, chỉ cần nhắn bot thêm một lần để tạo mã mới.

Sau khi duyệt, nhắn lại cho bot: lần này agent sẽ trả lời bằng model bạn đã cấu hình.

Vì sao OpenClaw bắt duyệt như vậy? Bot Telegram là công khai, ai biết username đều nhắn được. Nếu không có bước pairing, một người lạ có thể dùng agent của bạn, tốn API key của bạn và ra lệnh cho agent chạy trên VPS của bạn. Đừng đổi dmPolicy sang chế độ mở nếu bạn không hiểu rõ rủi ro.

Ai được nói chuyện với bot: tin nhắn riêng cần duyệt pairing, trong group cần group và người gửi đều nằm trong allowlist và nhắc tên bot

Bước 4: Đưa bot vào group (tuỳ chọn)

Bot trong group hợp với nhóm nhỏ cùng làm việc, ví dụ hỏi agent tóm tắt tài liệu hay tra cứu nhanh. Trong group, OpenClaw kiểm tra hai lớp: group đó có được cho phép không, và người gửi có được cho phép không. Lưu ý: việc bạn đã duyệt pairing ở tin nhắn riêng không áp dụng cho group, nên bạn phải khai báo cả ID của group lẫn ID Telegram của từng người được dùng bot.

  1. Thêm bot vào group như thêm một thành viên.
  2. Lấy ID của group và User ID của bạn: chạy openclaw logs --follow trên VPS rồi nhắn một câu trong group, cả hai ID sẽ hiện trong log. ID của supergroup bắt đầu bằng -100; User ID là một dãy số dương. Bạn cũng có thể lấy User ID bằng cách nhắn @userinfobot.
  3. Thêm ID group làm khoá trong channels.telegram.groups, kèm danh sách người được dùng bot trong allowFrom. requireMention: true nghĩa là bot chỉ trả lời khi được nhắc tên, tránh việc agent chen vào mọi câu chuyện trong group:
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["123456789"],
        },
      },
    },
  },
}

Muốn thêm đồng nghiệp, thêm User ID của họ vào mảng allowFrom. Đừng đặt ID group (số âm) vào allowFrom: chỗ đó chỉ dành cho User ID.

  1. Trong group, gõ /whoami@<username_bot> để kiểm tra bot đã nhận đúng các ID.

Privacy mode: vì sao bot không thấy tin nhắn trong group

Bot Telegram mặc định bật Privacy Mode, chỉ nhận một phần tin nhắn trong group. Với requireMention: true, như vậy thường là đủ, vì bot chỉ cần thấy tin nhắn có nhắc tên nó. Nếu muốn bot đọc mọi tin nhắn, gửi /setprivacy cho BotFather để tắt, hoặc đặt bot làm admin của group. Sau khi đổi, hãy xoá bot khỏi group rồi thêm lại thì thay đổi mới có hiệu lực.

Lỗi hay gặp

Triệu chứng Nguyên nhân thường gặp Cách xử lý
Bot không trả lời tin nhắn riêng Chưa duyệt pairing openclaw pairing list telegram rồi duyệt mã
pairing approve báo mã không hợp lệ Mã đã quá 1 giờ Nhắn bot lại để lấy mã mới
Bot im lặng trong group Group chưa nằm trong allowlist, User ID của bạn chưa có trong allowFrom, hoặc chưa nhắc tên bot Thêm ID group vào groups và User ID vào allowFrom, nhắc @username_bot
Bot không thấy tin nhắn trong group Privacy Mode đang bật /setprivacy ở BotFather, rồi thêm lại bot vào group
channels status --probe báo lỗi token Token sai hoặc đã bị thu hồi Lấy token mới bằng /token ở BotFather

Khi đã chat được với agent qua Telegram, bạn có thể cho nó tự gửi báo cáo theo lịch với HEARTBEAT.md, và nhớ tối ưu token vì tin nhắn qua Telegram cũng tính vào hoá đơn API.

Trên OnMay: kết nối Telegram ngay trong console

Nếu VPS của bạn chạy trên OnMay, không cần SSH để làm các bước trên. Trong tab OpenClaw của console, mục Kết nối kênh giao tiếp cho bạn dán bot token từ BotFather và User ID Telegram của bạn (lấy từ @userinfobot), rồi duyệt mã pairing ngay trên giao diện. OpenClaw đã cài sẵn trên mọi gói, Starter từ 149.000đ/tháng.

Tạo VPS có sẵn OpenClaw trên OnMay

Tất cả bài viếtTạo VPS ngay