WhatsApp

Trạng thái: sẵn sàng cho production qua WhatsApp Web (Baileys). Gateway sở hữu phiên đã liên kết.

# Cài đặt (theo nhu cầu)

• Onboarding (openclaw onboard) và openclaw channels add --channel whatsapp sẽ nhắc cài đặt Plugin WhatsApp vào lần đầu bạn chọn nó.
• openclaw channels login --channel whatsapp cũng cung cấp luồng cài đặt khi Plugin chưa có.
• Kênh dev + git checkout: mặc định dùng đường dẫn Plugin cục bộ.
• Stable/Beta: dùng gói npm @openclaw/whatsapp trên tag bản phát hành chính thức hiện tại.

Cài đặt thủ công vẫn khả dụng:

openclaw plugins install @openclaw/whatsapp

Dùng gói trần để theo tag bản phát hành chính thức hiện tại. Chỉ ghim một phiên bản chính xác khi bạn cần một bản cài đặt có thể tái lập.

Trên Windows, Plugin WhatsApp cần Git trên PATH trong khi cài đặt npm vì một trong các dependency Baileys/libsignal của nó được lấy từ một URL git. Cài đặt Git for Windows, rồi khởi động lại shell và chạy lại cài đặt:

winget install --id Git.Git -e

Portable Git cũng hoạt động nếu thư mục bin của nó nằm trên PATH.

# Thiết lập nhanh

{
channels: {
whatsapp: {
  dmPolicy: "pairing",
  allowFrom: ["+15551234567"],
  groupPolicy: "allowlist",
  groupAllowFrom: ["+15551234567"],
},
},
}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# Mẫu triển khai

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

# Mô hình runtime

• Gateway sở hữu socket WhatsApp và vòng lặp kết nối lại.
• Watchdog kết nối lại dùng hoạt động transport WhatsApp Web, không chỉ khối lượng tin nhắn ứng dụng inbound, nên một phiên thiết bị đã liên kết đang yên lặng sẽ không bị khởi động lại chỉ vì gần đây không ai gửi tin nhắn. Một ngưỡng im lặng ứng dụng dài hơn vẫn buộc kết nối lại nếu các frame transport vẫn đến nhưng không có tin nhắn ứng dụng nào được xử lý trong cửa sổ watchdog; sau một lần kết nối lại tạm thời cho phiên hoạt động gần đây, kiểm tra im lặng ứng dụng đó dùng timeout tin nhắn bình thường cho cửa sổ khôi phục đầu tiên.
• Thời điểm socket Baileys được đặt rõ dưới web.whatsapp.*: keepAliveIntervalMs điều khiển ping ứng dụng WhatsApp Web, connectTimeoutMs điều khiển timeout bắt tay mở kết nối, và defaultQueryTimeoutMs điều khiển timeout truy vấn Baileys.
• Gửi outbound yêu cầu một listener WhatsApp đang hoạt động cho tài khoản đích.
• Gửi nhóm đính kèm metadata nhắc đến gốc cho các token @+<digits> và @<digits> trong văn bản và chú thích media khi token khớp metadata người tham gia WhatsApp hiện tại, bao gồm các nhóm dựa trên LID.
• Chat trạng thái và broadcast bị bỏ qua (@status, @broadcast).
• Watchdog kết nối lại theo dõi hoạt động transport WhatsApp Web, không chỉ khối lượng tin nhắn ứng dụng inbound: phiên thiết bị đã liên kết yên lặng vẫn duy trì khi các frame transport tiếp tục, nhưng transport bị treo sẽ buộc kết nối lại trước rất lâu so với đường ngắt kết nối từ xa muộn hơn.
• Chat trực tiếp dùng quy tắc phiên DM (session.dmScope; mặc định main gom DM vào phiên chính của agent).
• Phiên nhóm được cô lập (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters có thể là đích outbound tường minh bằng JID @newsletter gốc của chúng. Gửi outbound newsletter dùng metadata phiên kênh (agent:<agentId>:whatsapp:channel:<jid>) thay vì ngữ nghĩa phiên DM.
• Transport WhatsApp Web tôn trọng các biến môi trường proxy chuẩn trên host Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / các biến chữ thường tương ứng). Ưu tiên cấu hình proxy cấp host hơn cài đặt proxy WhatsApp riêng theo kênh.
• Khi bật messages.removeAckAfterReply, OpenClaw xóa phản ứng ack của WhatsApp sau khi một phản hồi hiển thị được gửi.

# Hook Plugin và quyền riêng tư

Tin nhắn inbound WhatsApp có thể chứa nội dung tin nhắn cá nhân, số điện thoại, định danh nhóm, tên người gửi và các trường tương quan phiên. Vì lý do đó, WhatsApp không broadcast payload hook inbound message_received đến các Plugin trừ khi bạn chọn tham gia rõ ràng:

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

Bạn có thể giới hạn phạm vi chọn tham gia cho một tài khoản:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

Chỉ bật tùy chọn này cho các Plugin mà bạn tin cậy để nhận nội dung tin nhắn và định danh inbound WhatsApp.

# Kiểm soát truy cập và kích hoạt

# Hành vi số cá nhân và tự chat

Khi số tự thân đã liên kết cũng có trong allowFrom, các biện pháp bảo vệ tự chat WhatsApp được kích hoạt:

• bỏ qua biên nhận đã đọc cho lượt tự chat
• bỏ qua hành vi tự kích hoạt bằng JID nhắc đến vốn sẽ ping chính bạn
• nếu chưa đặt messages.responsePrefix, trả lời tự chat mặc định là [{identity.name}] hoặc [openclaw]

# Chuẩn hóa tin nhắn và ngữ cảnh

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

# Phân phối, chia đoạn và phương tiện

# Trích dẫn trả lời

WhatsApp hỗ trợ trích dẫn trả lời gốc, trong đó các phản hồi gửi ra hiển thị phần trích dẫn tin nhắn gửi vào. Điều khiển bằng channels.whatsapp.replyToMode.

Mặc định là "off". Ghi đè theo từng tài khoản dùng channels.whatsapp.accounts.<id>.replyToMode.

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

# Mức phản ứng

channels.whatsapp.reactionLevel điều khiển phạm vi agent sử dụng phản ứng emoji trên WhatsApp:

Mặc định: "minimal".

Ghi đè theo từng tài khoản dùng channels.whatsapp.accounts.<id>.reactionLevel.

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

# Phản ứng xác nhận

WhatsApp hỗ trợ phản ứng xác nhận tức thì khi nhận tin nhắn gửi vào qua channels.whatsapp.ackReaction. Phản ứng xác nhận bị chặn bởi reactionLevel — chúng bị bỏ qua khi reactionLevel là "off".

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

Ghi chú hành vi:

• được gửi ngay sau khi tin nhắn gửi vào được chấp nhận (trước trả lời)
• lỗi được ghi log nhưng không chặn việc phân phối phản hồi bình thường
• chế độ nhóm mentions phản ứng trong các lượt được kích hoạt bằng nhắc đến; kích hoạt nhóm always đóng vai trò bỏ qua bước kiểm tra này
• WhatsApp dùng channels.whatsapp.ackReaction (legacy messages.ackReaction không được dùng ở đây)

# Nhiều tài khoản và thông tin xác thực

# Công cụ, hành động và ghi cấu hình

• Hỗ trợ công cụ agent bao gồm hành động phản ứng WhatsApp (react).
• Cổng hành động:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Ghi cấu hình do kênh khởi tạo được bật mặc định (vô hiệu hóa qua channels.whatsapp.configWrites=false).

# Khắc phục sự cố

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# System prompts

WhatsApp hỗ trợ system prompts kiểu Telegram cho nhóm và cuộc trò chuyện trực tiếp qua các map groups và direct.

Thứ bậc phân giải cho tin nhắn nhóm:

Map groups hiệu lực được xác định trước: nếu tài khoản định nghĩa groups riêng, nó thay thế hoàn toàn map groups gốc (không deep merge). Sau đó việc tra cứu prompt chạy trên một map duy nhất thu được:

1. System prompt dành riêng cho nhóm (groups["<groupId>"].systemPrompt): được dùng khi mục nhóm cụ thể tồn tại trong map và khóa systemPrompt của nó được định nghĩa. Nếu systemPrompt là chuỗi rỗng (""), ký tự đại diện bị bỏ qua và không áp dụng system prompt nào.
2. System prompt ký tự đại diện nhóm (groups["*"].systemPrompt): được dùng khi mục nhóm cụ thể hoàn toàn không có trong map, hoặc khi mục đó tồn tại nhưng không định nghĩa khóa systemPrompt.

Thứ bậc phân giải cho tin nhắn trực tiếp:

Map direct hiệu lực được xác định trước: nếu tài khoản định nghĩa direct riêng, nó thay thế hoàn toàn map direct gốc (không deep merge). Sau đó việc tra cứu prompt chạy trên một map duy nhất thu được:

1. Prompt hệ thống dành riêng cho trò chuyện trực tiếp (direct["<peerId>"].systemPrompt): được dùng khi mục peer cụ thể tồn tại trong map và khóa systemPrompt của mục đó được định nghĩa. Nếu systemPrompt là chuỗi rỗng (""), wildcard sẽ bị chặn và không áp dụng prompt hệ thống nào.
2. Prompt hệ thống wildcard cho trò chuyện trực tiếp (direct["*"].systemPrompt): được dùng khi mục peer cụ thể hoàn toàn không có trong map, hoặc khi mục đó tồn tại nhưng không định nghĩa khóa systemPrompt.

Khác biệt so với hành vi đa tài khoản của Telegram: Trong Telegram, groups ở root được chủ ý chặn cho tất cả tài khoản trong thiết lập đa tài khoản — kể cả những tài khoản không tự định nghĩa groups — để ngăn bot nhận tin nhắn nhóm từ các nhóm mà nó không thuộc về. WhatsApp không áp dụng cơ chế bảo vệ này: groups ở root và direct ở root luôn được kế thừa bởi các tài khoản không định nghĩa ghi đè ở cấp tài khoản, bất kể có bao nhiêu tài khoản được cấu hình. Trong thiết lập WhatsApp đa tài khoản, nếu bạn muốn prompt nhóm hoặc trò chuyện trực tiếp theo từng tài khoản, hãy định nghĩa rõ toàn bộ map dưới từng tài khoản thay vì dựa vào mặc định ở cấp root.

Hành vi quan trọng:

• channels.whatsapp.groups vừa là map cấu hình theo từng nhóm vừa là allowlist nhóm ở cấp chat. Ở phạm vi root hoặc tài khoản, groups["*"] nghĩa là "tất cả nhóm đều được chấp nhận" cho phạm vi đó.
• Chỉ thêm wildcard nhóm systemPrompt khi bạn đã muốn phạm vi đó chấp nhận tất cả nhóm. Nếu bạn vẫn chỉ muốn một tập ID nhóm cố định đủ điều kiện, đừng dùng groups["*"] làm mặc định prompt. Thay vào đó, hãy lặp lại prompt trên từng mục nhóm được allowlist rõ ràng.
• Việc chấp nhận nhóm và ủy quyền người gửi là các kiểm tra riêng biệt. groups["*"] mở rộng tập nhóm có thể đi tới xử lý nhóm, nhưng bản thân nó không ủy quyền cho mọi người gửi trong các nhóm đó. Quyền truy cập của người gửi vẫn được kiểm soát riêng bởi channels.whatsapp.groupPolicy và channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct không có tác dụng phụ tương tự đối với DM. direct["*"] chỉ cung cấp cấu hình trò chuyện trực tiếp mặc định sau khi một DM đã được chấp nhận bởi dmPolicy cộng với allowFrom hoặc các quy tắc pairing-store.

Ví dụ:

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "[email protected]": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

# Con trỏ tham chiếu cấu hình

Tham chiếu chính:

• Tham chiếu cấu hình - WhatsApp

Các trường WhatsApp có tín hiệu cao:

• truy cập: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• gửi nhận: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• đa tài khoản: accounts.<id>.enabled, accounts.<id>.authDir, các ghi đè cấp tài khoản
• vận hành: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• hành vi phiên: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompt: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# Liên quan

• Ghép nối
• Nhóm
• Bảo mật
• Định tuyến kênh
• Định tuyến đa tác tử
• Khắc phục sự cố