4. Security - Pairing & Allowlist (BẮT BUỘC)

⚠️ Đọc kỹ - Không thiết lập security = Bot mở cửa cho spam và abuse.

Tại sao cần security?

Nếu không bật security:

• Bot nhận tin nhắn từ bất kỳ ai
• Dễ bị spam, abuse
• API key có thể bị lạm dụng

Hai lớp bảo vệ

┌─────────────────────────────────────┐
│         DM Pairing                  │  ← Lớp 1: Kiểm soát ai có thể nhắn tin
│  (Người lạ cần mã phê duyệt)       │
└─────────────────────────────────────┘
            ↓
┌─────────────────────────────────────┐
│         Allowlist                   │  ← Lớp 2: Danh sách cho phép cụ thể
│  (Chỉ người trong list được trả lời)│
└─────────────────────────────────────┘

Bước 1: Bật DM Pairing

Cấu hình cho Telegram

openclaw config set channels.telegram.dmPolicy "pairing"

Cấu hình cho WhatsApp

openclaw config set channels.whatsapp.dmPolicy "pairing"

Cấu hình cho Discord

openclaw config set channels.discord.dmPolicy "pairing"

Giải thích chính sách

Policy	Ý nghĩa	Khi nào dùng
pairing	Người lạ cần mã phê duyệt	Khuyến nghị cho bot công khai
open	Ai cũng chat được	Chỉ dùng cho private bot
disabled	Tắt hoàn toàn DM	Không nhận tin nhắn riêng

Bước 2: Cách Pairing hoạt động

Luồng pairing

1. Người lạ gửi tin nhắn đến bot
        ↓
2. Bot tự động tạo mã 8 ký tự (VD: ABC12345)
        ↓
3. Bot gửi mã cho người lạ: "Mã pairing: ABC12345"
        ↓
4. Bạn nhận thông báo có yêu cầu mới
        ↓
5. Bạn phê duyệt: openclaw pairing approve telegram ABC12345
        ↓
6. Người dùng được thêm vào allowlist
        ↓
7. Các tin nhắn sau hoạt động bình thường

Đặc điểm mã pairing

• 8 ký tự, chữ hoa, không dễ nhầm (0, O, 1, I)
• Hết hạn sau 1 giờ
• Tối đa 3 yêu cầu đang chờ mỗi kênh
• 1 tin/giờ cho mỗi người (tránh spam)

Bước 3: Quản lý pairing qua CLI

Liệt kê yêu cầu đang chờ

# Telegram
openclaw pairing list telegram

# WhatsApp
openclaw pairing list whatsapp

# Discord
openclaw pairing list discord

Output:

Pending Pairing Requests (telegram):
├─ Code: ABC12345 | User: @johndoe | Time: 2024-01-15 10:30
└─ Code: XYZ98765 | User: @janedoe | Time: 2024-01-15 10:45

Phê duyệt

openclaw pairing approve telegram ABC12345

Từ chối

openclaw pairing reject telegram ABC12345

Bước 4: Quản lý Allowlist

Allowlist là danh sách người được phép chat không cần pairing.

Thêm người vào allowlist

Telegram (dùng User ID):

openclaw allowlist add telegram 123456789

WhatsApp (dùng số điện thoại):

openclaw allowlist add whatsapp "+84123456789"

Discord (dùng User ID):

openclaw allowlist add discord 123456789012345678

Xóa người khỏi allowlist

openclaw allowlist remove telegram 123456789

Liệt kê allowlist

openclaw allowlist list telegram

Bước 5: Cấu hình nâng cao

Thay đổi thời gian hết hạn pairing

{
  channels: {
    telegram: {
      dmPolicy: "pairing",
      pairing: {
        timeout: "30m", // 30 phút (mặc định 1 giờ)
        maxAttempts: 3, // Số lần thử tối đa
      },
    },
  },
}

Cấu hình theo group (Discord/Slack)

{
  channels: {
    discord: {
      dmPolicy: "pairing",
      guilds: {
        "guild-id-1": {
          dmPolicy: "open", // Server này không cần pairing
        },
        "guild-id-2": {
          dmPolicy: "pairing", // Server này cần pairing
        },
      },
    },
  },
}

Bước 6: File lưu trữ

~/.openclaw/credentials/
├── telegram-pairing.json        # Yêu cầu đang chờ xử lý
├── telegram-allowFrom.json      # Danh sách được phép
├── whatsapp-pairing.json
├── whatsapp-allowFrom.json
└── discord-allowFrom.json

Không xóa thủ công - Dùng CLI để quản lý.

Best Practices

1. Luôn bật pairing cho bot công khai

openclaw config set channels.telegram.dmPolicy "pairing"

2. Giới hạn allowlist ngay từ đầu

# Thêm người tin cậy vào allowlist
openclaw allowlist add telegram 123456789
openclaw allowlist add telegram 987654321

3. Kiểm tra định kỳ

# Hàng tuần, kiểm tra allowlist
openclaw allowlist list telegram
openclaw allowlist list whatsapp

4. Không dùng dmPolicy: "open" cho bot công khai

Chỉ dùng open nếu:

• Bot chỉ dùng trong nhóm kín
• Bạn kiểm soát được ai có thể tìm thấy bot

Troubleshooting

"Mã pairing không hợp lệ"

• Mã đã hết hạn (1 giờ)
• Người dùng cần gửi lại tin nhắn để nhận mã mới

"Quá nhiều yêu cầu"

• Đã có 3 yêu cầu đang chờ
• Phê duyệt hoặc từ chối bớt yêu cầu cũ
• Hoặc chờ 1 giờ để mã hết hạn tự động

"Không nhận được yêu cầu pairing"

• Kiểm tra logs: openclaw logs --tail 100
• Xác nhận dmPolicy đã set đúng
• Kiểm tra bot token còn hoạt động

Tóm tắt

# 1. Bật pairing
openclaw config set channels.telegram.dmPolicy "pairing"

# 2. Kiểm tra yêu cầu đang chờ
openclaw pairing list telegram

# 3. Phê duyệt
openclaw pairing approve telegram ABC12345

# 4. Thêm người tin cậy vào allowlist
openclaw allowlist add telegram 123456789

Tiếp theo?

• Bài 5: Daily Usage - Bắt đầu sử dụng hàng ngày
• Bài 6: More Channels - Thêm WhatsApp, Discord, Slack