WhatsApp

​

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

• Onboarding (openclaw onboard) và openclaw channels add --channel whatsapp sẽ nhắc cài đặt Plugin WhatsApp trong lần đầu bạn chọn kênh này.
• 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: cài đặt Plugin @openclaw/whatsapp chính thức từ ClawHub trước, với npm làm phương án dự phòng.
• Runtime WhatsApp được phân phối bên ngoài gói npm OpenClaw lõi để các phụ thuộc runtime riêng của WhatsApp nằm cùng Plugin bên ngoài.

openclaw plugins install clawhub:@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>

​

Gọi người yêu cầu hiện tại bằng MeowCaller (thử nghiệm)

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -p "$HOME/.local/bin"
go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"
mkdir -p "$state_dir"
chmod 700 "$state_dir"
meowcaller pair --store "$state_dir/wa-voip.db"

• chỉ cuộc gọi âm thanh outbound một-một
• không có số đích tùy ý
• không chia sẻ xác thực với kết nối trò chuyện
• không tự gọi từ chế độ số cá nhân/tự trò chuyện
• âm thanh tổng hợp bị giới hạn ở 60 giây
• không có biên nhận nghe được ở phía thiết bị cầm tay ngoài hoàn tất trả lời/phát lại/gác máy của MeowCaller
• OpenClaw dừng tiến trình đồng hành sau một cửa sổ giới hạn 115-175 giây, bao gồm các pha kết nối, trả lời, phát lại và tắt của MeowCaller

​

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 truyền tải 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 yên lặng sẽ không bị khởi động lại chỉ vì gần đây không có 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 truyền tải 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 phiên vừa 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 gian socket Baileys được khai báo tường minh dưới web.whatsapp.*: keepAliveIntervalMs kiểm soát ping ứng dụng WhatsApp Web, connectTimeoutMs kiểm soát timeout bắt tay mở kết nối, và defaultQueryTimeoutMs kiểm soát thời gian chờ truy vấn Baileys cộng với giới hạn thao tác gửi/presence outbound cục bộ và biên nhận đọc inbound của OpenClaw.
• 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 gắn siêu dữ liệu mention gốc cho các token @+<digits> và @<digits> trong văn bản và chú thích media khi token khớp với siêu dữ liệu người tham gia WhatsApp hiện tại, bao gồm các nhóm dùng LID.
• 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 truyền tải WhatsApp Web, không chỉ khối lượng tin nhắn ứng dụng inbound: các phiên thiết bị liên kết yên lặng vẫn duy trì trong khi frame truyền tải tiếp tục, nhưng truyền tải bị ngừng 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 về sau.
• 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 cô lập (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters có thể là đích outbound tường minh với JID @newsletter gốc của chúng. Gửi newsletter outbound dùng siêu dữ liệu phiên kênh (agent:<agentId>:whatsapp:channel:<jid>) thay vì ngữ nghĩa phiên DM.
• Truyền tải WhatsApp Web tôn trọng các biến môi trường proxy tiêu chuẩn trên máy chủ Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / các biến chữ thường tương ứng). Nên dùng cấu hình proxy cấp máy chủ thay vì thiết lập 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.

​

Prompt phê duyệt

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session",
    },
    plugin: {
      enabled: true,
      mode: "targets",
      targets: [{ channel: "whatsapp", to: "+15551234567" }],
    },
  },
}

​

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

​

Liên kết ACP đã cấu hình

{
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "direct", id: "+15555550123" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "group", id: "120363424282127706@g.us" },
      },
    },
  ],
}

• Trò chuyện trực tiếp khớp các số E.164 như +15555550123.
• Nhóm khớp các JID nhóm WhatsApp như 120363424282127706@g.us.
• Allowlist nhóm, chính sách người gửi và cổng nhắc đến hoặc kích hoạt chạy trước khi OpenClaw bảo đảm phiên ACP đã cấu hình tồn tại.
• Một liên kết ACP đã cấu hình và khớp sẽ sở hữu tuyến. Nhóm phát rộng WhatsApp không phân tán lượt đó sang các phiên WhatsApp thông thường.

​

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ự động kích hoạt mention-JID vốn sẽ 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,
        },
      },
    },
  },
}

​

Gửi, chia đoạn và media

​

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 đến được chấp nhận (trước phản hồi)
• nếu có ackReaction nhưng không có emoji, WhatsApp dùng emoji danh tính của tác tử được định tuyến, dự phòng về ”👀”; bỏ qua ackReaction hoặc đặt emoji: "" để không gửi phản ứng xác nhận
• lỗi được ghi log nhưng không chặn việc gửi phản hồi thông thường
• chế độ nhóm mentions phản ứng trên các lượt được kích hoạt bằng lượt nhắc đến; kích hoạt nhóm always đóng vai trò bỏ qua kiểm tra này
• WhatsApp dùng channels.whatsapp.ackReaction (messages.ackReaction cũ không được dùng ở đây)

​

Phản ứng trạng thái vòng đời

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        concierge: "💁",
      },
    },
  },
}

• channels.whatsapp.ackReaction vẫn kiểm soát liệu phản ứng trạng thái có đủ điều kiện cho tin nhắn trực tiếp và nhóm hay không.
• Phản ứng trạng thái đã xếp hàng dùng cùng emoji xác nhận hiệu lực như phản ứng xác nhận thông thường.
• WhatsApp có một vị trí phản ứng bot cho mỗi tin nhắn, vì vậy các cập nhật vòng đời thay thế phản ứng hiện tại tại chỗ.
• messages.removeAckAfterReply: true xóa phản ứng trạng thái cuối cùng sau thời gian giữ hoàn tất/lỗi đã cấu hình.
• Các danh mục emoji công cụ bao gồm tool, coding, web, deploy, build và concierge.

​

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ụ tác tử 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 channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

Prompt hệ thống

1. Prompt hệ thống theo 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ị chặn và không áp dụng prompt hệ thống.
2. Prompt hệ thống 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 theo tin nhắ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 nó được định nghĩa. Nếu systemPrompt là chuỗi rỗng (""), ký tự đại diện bị chặn và không áp dụng prompt hệ thống.
2. Prompt hệ thống ký tự đại diện tin nhắ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 nhóm vừa là danh sách cho phép nhóm ở cấp 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 systemPrompt nhóm ký tự đại diện 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["*"] cho mặc định prompt. Thay vào đó, lặp lại prompt trên từng mục nhóm được cho phép rõ ràng.
• 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 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ó cùng tác dụng phụ đối với DM. direct["*"] chỉ cung cấp cấu hình cuộc 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 quy tắc kho ghép cặp.

{
  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
• phân phối: 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
• 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ố