WhatsApp

สถานะ: พร้อมใช้งานจริงผ่าน WhatsApp Web (Baileys) Gateway เป็นเจ้าของเซสชันที่ลิงก์

ติดตั้ง (เมื่อต้องการ)

• Onboarding (openclaw onboard) และ openclaw channels add --channel whatsapp จะแจ้งให้ติดตั้ง WhatsApp plugin เมื่อคุณเลือกใช้งานครั้งแรก
• openclaw channels login --channel whatsapp ยังเสนอขั้นตอนติดตั้งเมื่อ ยังไม่มี plugin อยู่
• ช่อง Dev + git checkout: ใช้ค่าเริ่มต้นเป็นพาธ plugin ภายในเครื่อง
• Stable/Beta: ติดตั้ง plugin อย่างเป็นทางการ @openclaw/whatsapp จาก ClawHub ก่อน โดยมี npm เป็นทางสำรอง
• WhatsApp runtime ถูกแจกจ่ายอยู่นอกแพ็กเกจ npm หลักของ OpenClaw เพื่อให้ runtime dependencies เฉพาะ WhatsApp อยู่กับ plugin ภายนอก

ยังสามารถติดตั้งด้วยตนเองได้:

openclaw plugins install clawhub:@openclaw/whatsapp

ใช้แพ็กเกจ npm แบบเปล่า (@openclaw/whatsapp) เฉพาะเมื่อคุณต้องการทางสำรองจาก registry ปักหมุดเวอร์ชันแบบเจาะจงเฉพาะเมื่อคุณต้องการการติดตั้งที่ทำซ้ำได้เท่านั้น

ตั้งค่าอย่างรวดเร็ว

{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-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

รูปแบบการปรับใช้

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

โมเดล Runtime

• Gateway เป็นเจ้าของ socket ของ WhatsApp และลูปเชื่อมต่อใหม่
• watchdog สำหรับการเชื่อมต่อใหม่ใช้กิจกรรมของ transport WhatsApp Web ไม่ใช่เฉพาะปริมาณข้อความแอปขาเข้า ดังนั้นเซสชันอุปกรณ์ที่ลิงก์ซึ่งเงียบจะไม่ถูกรีสตาร์ทเพียงเพราะไม่มีใครส่งข้อความมาเมื่อเร็ว ๆ นี้ เพดานความเงียบของแอปพลิเคชันที่ยาวกว่ายังคงบังคับให้เชื่อมต่อใหม่หาก transport frames ยังมาถึงแต่ไม่มีข้อความแอปพลิเคชันถูกจัดการภายในช่วง watchdog; หลังจากการเชื่อมต่อใหม่ชั่วคราวสำหรับเซสชันที่เพิ่งใช้งาน การตรวจสอบความเงียบของแอปพลิเคชันนั้นใช้ timeout ข้อความปกติสำหรับช่วงกู้คืนแรก
• การตั้งเวลา socket ของ Baileys ระบุไว้อย่างชัดเจนภายใต้ web.whatsapp.*: keepAliveIntervalMs ควบคุม ping แอปพลิเคชัน WhatsApp Web, connectTimeoutMs ควบคุม timeout ของ opening handshake และ defaultQueryTimeoutMs ควบคุมการรอ query ของ Baileys รวมถึงขอบเขตการดำเนินการส่ง/สถานะ presence ขาออกภายในเครื่องของ OpenClaw และ read-receipt ขาเข้า
• การส่งขาออกต้องมี listener ของ WhatsApp ที่ทำงานอยู่สำหรับบัญชีเป้าหมาย
• การส่งกลุ่มแนบข้อมูลเมตาการ mention แบบ native สำหรับโทเคน @+<digits> และ @<digits> ในข้อความและคำบรรยายสื่อเมื่อโทเคนตรงกับข้อมูลเมตาผู้เข้าร่วม WhatsApp ปัจจุบัน รวมถึงกลุ่มที่รองรับ LID
• แชทสถานะและบรอดแคสต์จะถูกละเว้น (@status, @broadcast)
• watchdog สำหรับการเชื่อมต่อใหม่ติดตามกิจกรรม transport ของ WhatsApp Web ไม่ใช่เฉพาะปริมาณข้อความแอปขาเข้า: เซสชันอุปกรณ์ที่ลิงก์ซึ่งเงียบยังคงอยู่ได้ขณะ transport frames ดำเนินต่อ แต่ transport stall จะบังคับให้เชื่อมต่อใหม่ก่อนเส้นทางตัดการเชื่อมต่อระยะไกลที่ตามมามาก
• แชทตรงใช้กฎเซสชัน DM (session.dmScope; ค่าเริ่มต้น main รวม DM ไปยังเซสชันหลักของ agent)
• เซสชันกลุ่มถูกแยกกัน (agent:<agentId>:whatsapp:group:<jid>)
• WhatsApp Channels/Newsletters สามารถเป็นเป้าหมายขาออกแบบชัดเจนด้วย JID @newsletter แบบ native ได้ การส่ง newsletter ขาออกใช้ข้อมูลเมตาเซสชันช่องทาง (agent:<agentId>:whatsapp:channel:<jid>) แทน semantics ของเซสชัน DM
• transport ของ WhatsApp Web เคารพตัวแปรสภาพแวดล้อม proxy มาตรฐานบนโฮสต์ gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / variants ตัวพิมพ์เล็ก) ควรใช้การกำหนดค่า proxy ระดับโฮสต์แทนการตั้งค่า proxy เฉพาะช่องทาง WhatsApp
• เมื่อเปิดใช้ messages.removeAckAfterReply OpenClaw จะล้าง reaction ack ของ WhatsApp หลังจากส่ง reply ที่มองเห็นได้แล้ว

พรอมต์อนุมัติ

WhatsApp สามารถแสดงพรอมต์อนุมัติ exec และ plugin ด้วย reaction 👍 / 👎 การส่งมอบ ถูกควบคุมโดยการกำหนดค่าการส่งต่อ approval ระดับบนสุด:

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

approvals.exec และ approvals.plugin เป็นอิสระต่อกัน การเปิดใช้ WhatsApp เป็นช่องทางเพียงลิงก์ transport เท่านั้น; จะไม่ส่งพรอมต์อนุมัติ เว้นแต่เปิดใช้ตระกูล approval ที่ตรงกัน และ route ไปยัง WhatsApp โหมด Session ส่งการอนุมัติด้วยอีโมจิ native เฉพาะสำหรับ approval ที่ มีต้นทางจาก WhatsApp โหมด Target ใช้ pipeline การส่งต่อร่วมสำหรับเป้าหมาย WhatsApp ที่ระบุชัดเจน และไม่สร้าง approver-DM fanout แยกต่างหาก

reaction อนุมัติของ WhatsApp ต้องมีผู้อนุมัติ WhatsApp ที่ระบุชัดเจนจาก allowFrom หรือ "*" defaultTo ควบคุมเป้าหมายข้อความเริ่มต้นทั่วไป; ไม่ใช่ผู้อนุมัติ approval คำสั่ง /approve แบบ manual ยังคงผ่านเส้นทาง authorization ผู้ส่ง WhatsApp ตามปกติก่อน การตัดสิน approval

Plugin hooks และความเป็นส่วนตัว

ข้อความขาเข้าของ WhatsApp อาจมีเนื้อหาข้อความส่วนตัว หมายเลขโทรศัพท์ ตัวระบุกลุ่ม ชื่อผู้ส่ง และฟิลด์เชื่อมโยงเซสชัน ด้วยเหตุนี้ WhatsApp จึงไม่ broadcast payload hook ขาเข้า message_received ไปยัง plugins เว้นแต่คุณเลือกเปิดใช้โดยชัดเจน:

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

คุณสามารถจำกัดการเลือกเปิดใช้ให้กับบัญชีเดียวได้:

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

เปิดใช้เฉพาะกับ plugins ที่คุณไว้วางใจให้รับเนื้อหาข้อความ และตัวระบุของ WhatsApp ขาเข้าเท่านั้น

การควบคุมการเข้าถึงและการเปิดใช้งาน

การผูก ACP ที่กำหนดค่าไว้

WhatsApp รองรับการผูก ACP แบบถาวรด้วยรายการ bindings[] ระดับบนสุด:

{  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" },      },    },  ],}

• แชทโดยตรงจับคู่กับหมายเลข E.164 เช่น +15555550123.
• กลุ่มจับคู่กับ WhatsApp group JIDs เช่น 120363424282127706@g.us.
• รายการอนุญาตของกลุ่ม นโยบายผู้ส่ง และการกั้นด้วยการกล่าวถึงหรือการเปิดใช้งาน จะทำงานก่อนที่ OpenClaw จะตรวจสอบว่ามีเซสชัน ACP ที่กำหนดค่าไว้แล้ว
• การผูก ACP ที่กำหนดค่าไว้และจับคู่ได้จะเป็นเจ้าของเส้นทาง กลุ่มบรอดแคสต์ WhatsApp จะไม่กระจายเทิร์นนั้นไปยังเซสชัน WhatsApp ปกติ

พฤติกรรมหมายเลขส่วนตัวและแชทกับตัวเอง

เมื่อหมายเลขตนเองที่ลิงก์ไว้มีอยู่ใน allowFrom ด้วย ระบบป้องกันแชทกับตัวเองของ WhatsApp จะเปิดใช้งาน:

• ข้ามใบตอบรับการอ่านสำหรับเทิร์นแชทกับตัวเอง
• เพิกเฉยต่อพฤติกรรมทริกเกอร์อัตโนมัติด้วย mention-JID ที่มิฉะนั้นจะ ping ตัวคุณเอง
• หากไม่ได้ตั้งค่า messages.responsePrefix คำตอบในแชทกับตัวเองจะใช้ค่าเริ่มต้นเป็น [{identity.name}] หรือ [openclaw]

การทำให้ข้อความเป็นมาตรฐานและบริบท

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

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

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

การส่ง การแบ่งชิ้น และสื่อ

การอ้างอิงข้อความตอบกลับ

WhatsApp รองรับการอ้างอิงข้อความตอบกลับแบบ native ซึ่งคำตอบขาออกจะแสดงการอ้างอิงข้อความขาเข้าอย่างชัดเจน ควบคุมด้วย channels.whatsapp.replyToMode

ค่าเริ่มต้นคือ "off" override ต่อบัญชีใช้ channels.whatsapp.accounts.<id>.replyToMode

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

ระดับปฏิกิริยา

channels.whatsapp.reactionLevel ควบคุมว่า agent ใช้ปฏิกิริยาอีโมจิบน WhatsApp กว้างเพียงใด:

ค่าเริ่มต้น: "minimal"

override ต่อบัญชีใช้ channels.whatsapp.accounts.<id>.reactionLevel

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

ปฏิกิริยารับทราบ

WhatsApp รองรับปฏิกิริยา ack ทันทีเมื่อได้รับขาเข้า ผ่าน channels.whatsapp.ackReaction ปฏิกิริยา Ack ถูกกั้นด้วย reactionLevel — จะถูกระงับเมื่อ reactionLevel เป็น "off"

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

หมายเหตุพฤติกรรม:

• ส่งทันทีหลังจากรับขาเข้าแล้ว (ก่อนตอบกลับ)
• หากมี ackReaction โดยไม่มี emoji WhatsApp จะใช้อีโมจิ identity ของ agent ที่ถูก route โดย fallback ไปเป็น "👀"; ละเว้น ackReaction หรือตั้ง emoji: "" เพื่อไม่ส่งปฏิกิริยา ack
• ความล้มเหลวจะถูกบันทึก log แต่ไม่บล็อกการส่งคำตอบปกติ
• โหมดกลุ่ม mentions ตอบสนองต่อเทิร์นที่ทริกเกอร์ด้วยการกล่าวถึง; การเปิดใช้งานกลุ่ม always ทำหน้าที่เป็น bypass สำหรับการตรวจนี้
• WhatsApp ใช้ channels.whatsapp.ackReaction (ไม่ใช้ messages.ackReaction แบบ legacy ที่นี่)

ปฏิกิริยาสถานะวงจรชีวิต

ตั้งค่า messages.statusReactions.enabled: true เพื่อให้ WhatsApp แทนที่ปฏิกิริยา ack ระหว่างเทิร์น แทนการปล่อยอีโมจิใบตอบรับแบบคงที่ไว้ เมื่อเปิดใช้งาน OpenClaw จะใช้ช่องปฏิกิริยาของข้อความขาเข้าเดียวกันสำหรับสถานะวงจรชีวิต เช่น queued, thinking, tool activity, compaction, done และ error

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

หมายเหตุพฤติกรรม:

• channels.whatsapp.ackReaction ยังคงควบคุมว่าปฏิกิริยาสถานะมีสิทธิ์ใช้กับข้อความโดยตรงและกลุ่มหรือไม่
• ปฏิกิริยาสถานะ queued ใช้อีโมจิ ack ที่มีผลเดียวกับปฏิกิริยา ack ธรรมดา
• WhatsApp มีช่องปฏิกิริยาของบอตหนึ่งช่องต่อข้อความ ดังนั้นการอัปเดตวงจรชีวิตจะแทนที่ปฏิกิริยาปัจจุบันในที่เดิม
• messages.removeAckAfterReply: true ล้างปฏิกิริยาสถานะสุดท้ายหลังจากช่วงคงสถานะ done/error ที่กำหนดค่าไว้
• หมวดหมู่อีโมจิของเครื่องมือประกอบด้วย tool, coding, web, deploy, build และ concierge

หลายบัญชีและข้อมูลรับรอง

เครื่องมือ การกระทำ และการเขียนการกำหนดค่า

• การรองรับเครื่องมือของ agent รวมถึงการกระทำปฏิกิริยาของ WhatsApp (react)
• การกั้นการกระทำ:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• การเขียนการกำหนดค่าที่เริ่มโดย channel เปิดใช้งานเป็นค่าเริ่มต้น (ปิดใช้งานผ่าน channels.whatsapp.configWrites=false)

การแก้ปัญหา

openclaw channels login --channel whatsappopenclaw channels status

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

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

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

พรอมต์ระบบ

WhatsApp รองรับพรอมต์ระบบสไตล์ Telegram สำหรับกลุ่มและแชทโดยตรงผ่านแมป groups และ direct

ลำดับชั้นการแก้ค่าสำหรับข้อความกลุ่ม:

แมป groups ที่มีผลจะถูกกำหนดก่อน: หากบัญชีกำหนด groups ของตนเอง ระบบจะแทนที่แมป groups ระดับ root ทั้งหมด (ไม่มี deep merge) จากนั้นการค้นหาพรอมต์จะทำงานบนแมปเดี่ยวที่ได้:

1. พรอมต์ระบบเฉพาะกลุ่ม (groups["<groupId>"].systemPrompt): ใช้เมื่อมีรายการกลุ่มเฉพาะอยู่ในแมป และ มีการกำหนดคีย์ systemPrompt ของรายการนั้น หาก systemPrompt เป็นสตริงว่าง ("") wildcard จะถูกระงับและจะไม่ใช้พรอมต์ระบบ
2. พรอมต์ระบบ wildcard ของกลุ่ม (groups["*"].systemPrompt): ใช้เมื่อไม่มีรายการกลุ่มเฉพาะอยู่ในแมปเลย หรือเมื่อมีอยู่แต่ไม่ได้กำหนดคีย์ systemPrompt

ลำดับชั้นการแก้ค่าสำหรับข้อความโดยตรง:

แมป direct ที่มีผลจะถูกกำหนดก่อน: หากบัญชีกำหนด direct ของตนเอง ระบบจะแทนที่แมป direct ระดับ root ทั้งหมด (ไม่มี deep merge) จากนั้นการค้นหาพรอมต์จะทำงานบนแมปเดี่ยวที่ได้:

1. พรอมต์ระบบเฉพาะ direct (direct["<peerId>"].systemPrompt): ใช้เมื่อมีรายการ peer เฉพาะอยู่ในแมป และ มีการกำหนดคีย์ systemPrompt ของรายการนั้น หาก systemPrompt เป็นสตริงว่าง ("") wildcard จะถูกระงับและจะไม่ใช้พรอมต์ระบบ
2. พรอมต์ระบบ wildcard ของ direct (direct["*"].systemPrompt): ใช้เมื่อไม่มีรายการ peer เฉพาะอยู่ในแมปเลย หรือเมื่อมีอยู่แต่ไม่ได้กำหนดคีย์ systemPrompt

ความแตกต่างจากพฤติกรรมหลายบัญชีของ Telegram: ใน Telegram ค่า groups ระดับ root จะถูกระงับโดยตั้งใจสำหรับทุกบัญชีในการตั้งค่าหลายบัญชี แม้แต่บัญชีที่ไม่ได้กำหนด groups ของตนเอง เพื่อป้องกันไม่ให้บอทรับข้อความกลุ่มสำหรับกลุ่มที่บอทไม่ได้เป็นสมาชิก WhatsApp ไม่ใช้ guard นี้: groups ระดับ root และ direct ระดับ root จะถูกสืบทอดโดยบัญชีที่ไม่ได้กำหนด override ระดับบัญชีเสมอ ไม่ว่าจะกำหนดค่ากี่บัญชีก็ตาม ในการตั้งค่า WhatsApp หลายบัญชี หากคุณต้องการพรอมต์กลุ่มหรือ direct แยกตามบัญชี ให้กำหนดแมปทั้งหมดภายใต้แต่ละบัญชีอย่างชัดเจน แทนที่จะพึ่งค่าเริ่มต้นระดับ root

พฤติกรรมสำคัญ:

• channels.whatsapp.groups เป็นทั้งแมป config รายกลุ่มและ allowlist กลุ่มระดับแชท ที่ scope ระดับ root หรือบัญชี groups["*"] หมายถึง "รับทุกกลุ่มไว้" สำหรับ scope นั้น
• เพิ่ม wildcard group systemPrompt เฉพาะเมื่อคุณต้องการให้ scope นั้นรับทุกกลุ่มอยู่แล้ว หากคุณยังต้องการให้เฉพาะชุด ID กลุ่มที่กำหนดไว้เท่านั้นมีสิทธิ์ อย่าใช้ groups["*"] เป็นค่าเริ่มต้นของพรอมต์ ให้ทำซ้ำพรอมต์ในแต่ละรายการกลุ่มที่อยู่ใน allowlist อย่างชัดเจนแทน
• การรับกลุ่มและการอนุญาตผู้ส่งเป็นการตรวจสอบแยกกัน groups["*"] ขยายชุดกลุ่มที่สามารถเข้าถึงการจัดการกลุ่มได้ แต่ไม่ได้อนุญาตผู้ส่งทุกคนในกลุ่มเหล่านั้นด้วยตัวเอง การเข้าถึงของผู้ส่งยังคงถูกควบคุมแยกต่างหากโดย channels.whatsapp.groupPolicy และ channels.whatsapp.groupAllowFrom
• channels.whatsapp.direct ไม่มีผลข้างเคียงแบบเดียวกันสำหรับ DM direct["*"] ให้เฉพาะ config แชท direct เริ่มต้นหลังจาก DM ได้รับการรับไว้แล้วโดย dmPolicy ร่วมกับ allowFrom หรือกฎ 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." },          },        },      },    },  },}

ตัวชี้ไปยังข้อมูลอ้างอิงการกำหนดค่า

ข้อมูลอ้างอิงหลัก:

• ข้อมูลอ้างอิงการกำหนดค่า - WhatsApp

ฟิลด์ WhatsApp ที่มีสัญญาณสูง:

• การเข้าถึง: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• การส่งมอบ: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• หลายบัญชี: accounts.<id>.enabled, accounts.<id>.authDir, override ระดับบัญชี
• การปฏิบัติการ: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• พฤติกรรม session: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• พรอมต์: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

ที่เกี่ยวข้อง

• การจับคู่
• กลุ่ม
• ความปลอดภัย
• การกำหนดเส้นทางช่องทาง
• การกำหนดเส้นทางหลาย agent
• การแก้ไขปัญหา