WhatsApp

Documentation Index

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

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

​

Cài đặt (khi cần)

• Onboarding (openclaw onboard) và openclaw channels add --channel whatsapp 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 khi một gói hiện hành đã được phát hành.

openclaw plugins install @openclaw/whatsapp

​

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 của WhatsApp Web, không chỉ khối lượng tin nhắn ứng dụng đến, nên một phiên thiết bị đã liên kết yên lặng không bị khởi động lại chỉ vì gần đây không ai gửi tin nhắn. Một giới hạn 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 tiếp tục đế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 một phiên vừa hoạt động gần đây, kiểm tra im lặng ứng dụng đó dùng thời gian chờ tin nhắn bình thường cho cửa sổ khôi phục đầu tiên.
• Thời lượng socket Baileys được khai báo rõ dưới web.whatsapp.*: keepAliveIntervalMs kiểm soát ping ứng dụng WhatsApp Web, connectTimeoutMs kiểm soát thời gian chờ bắt tay mở kết nối, và defaultQueryTimeoutMs kiểm soát thời gian chờ truy vấn Baileys.
• Gửi ra ngoài yêu cầu một trình lắng nghe WhatsApp đang hoạt động cho tài khoản đích.
• Trò chuyện 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 của WhatsApp Web, không chỉ khối lượng tin nhắn ứng dụng đến: các phiên thiết bị đã liên kết yên lặng vẫn hoạt động khi frame transport tiếp tục, nhưng transport bị treo sẽ buộc kết nối lại sớm hơn nhiều so với đường ngắt kết nối từ xa muộn hơn.
• Trò chuyện trực tiếp dùng quy tắc phiên DM (session.dmScope; mặc định main gộp DM vào phiên chính của agent).
• Phiên nhóm được tách biệt (agent:<agentId>:whatsapp:group:<jid>).
• Transport WhatsApp Web tôn trọng các biến môi trường proxy chuẩn trên máy chủ Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / các biến viết thường tương ứng). Ưu tiên cấu hình proxy cấp máy chủ hơn cài đặt proxy WhatsApp riêng theo kênh.
• Khi messages.removeAckAfterReply được bật, OpenClaw xóa phản ứng ack WhatsApp sau khi 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ự trò chuyện

• bỏ qua biên nhận đã đọc cho các lượt tự trò chuyện
• bỏ qua hành vi tự kích hoạt bằng JID nhắc đến vốn có thể tự ping chính bạn
• nếu chưa đặt messages.responsePrefix, trả lời tự trò chuyện 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 khi trả lời)
• lỗi được ghi nhật ký nhưng không chặn việc gửi trả lời bình thường
• chế độ nhóm mentions phản ứng ở các lượt được kích hoạt bởi lượt nhắc đến; kích hoạt nhóm always hoạt động như đường vòng cho kiểm tra này
• WhatsApp dùng channels.whatsapp.ackReaction (messages.ackReaction cũ 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ụ của 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 theo mặc định (tắt 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

​

Prompt hệ thống

1. Prompt hệ thống theo nhóm cụ thể (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 (""), wildcard bị chặn và không áp dụng prompt hệ thống.
2. Prompt hệ thống wildcard cho nhóm (groups["*"].systemPrompt): được dùng khi mục nhóm cụ thể hoàn toàn vắng mặt trong map, hoặc khi nó tồn tại nhưng không định nghĩa khóa systemPrompt.

1. Prompt hệ thống theo trực tiếp cụ thể (direct["<peerId>"].systemPrompt): được dùng khi mục peer 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 (""), wildcard bị chặn và không áp dụng prompt hệ thống.
2. Prompt hệ thống wildcard cho trực tiếp (direct["*"].systemPrompt): được dùng khi mục peer cụ thể hoàn toàn vắng mặt trong map, hoặc khi nó 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 cuộc trò chuyện. Ở phạm vi gốc hoặc tài khoản, groups["*"] nghĩa là “tất cả nhóm đượ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 muốn chỉ một tập cố định các ID nhóm đủ điều kiện, đừng dùng groups["*"] cho mặc định prompt. Thay vào đó, lặp lại prompt trên từng mục nhóm được allowlist rõ ràng.
• Tiế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 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 điều khiển riêng bởi channels.whatsapp.groupPolicy và channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct không có cùng tác dụng phụ cho DM. direct["*"] chỉ cung cấp cấu hình trò chuyện trực tiếp mặc định sau khi DM đã được chấp nhận bởi dmPolicy cùng với allowFrom hoặc quy tắc kho ghép nối.

{
  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

• quyền truy cập: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• gửi: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• nhiều tài khoản: accounts.<id>.enabled, accounts.<id>.authDir, 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
• lời nhắc: 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 nhân
• Khắc phục sự cố