WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

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ư

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

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

​

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

​

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

• 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

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

​

Mức phản ứng

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

​

Phản ứng xác nhận

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

• đượ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

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.

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.

• 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.

{
  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.
            "120363406415684625@g.us": {
              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 cấu hình - WhatsApp

• 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ố