WhatsApp

สถานะ: พร้อมใช้งาน production ผ่าน WhatsApp Web (Baileys) Gateway เป็นเจ้าของเซสชันที่เชื่อมโยง

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

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

การติดตั้งด้วยตนเองยังคงใช้ได้:

openclaw plugins install @openclaw/whatsapp

ใช้แพ็กเกจแบบ bare เพื่อตามแท็ก release อย่างเป็นทางการปัจจุบัน ปักหมุด เวอร์ชันแบบแน่นอนเฉพาะเมื่อคุณต้องการการติดตั้งที่ทำซ้ำได้เท่านั้น

บน Windows Plugin WhatsApp ต้องใช้ Git บน PATH ระหว่าง npm install เพราะ หนึ่งใน dependency Baileys/libsignal ถูกดึงมาจาก git URL ให้ติดตั้ง Git for Windows จากนั้นรีสตาร์ต shell แล้วรันการติดตั้งอีกครั้ง:

winget install --id Git.Git -e

Portable Git ก็ใช้ได้เช่นกันถ้าไดเรกทอรี bin ของมันอยู่บน PATH

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

{
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>

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

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

# โมเดล runtime

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

# hook ของ Plugin และความเป็นส่วนตัว

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

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

คุณสามารถจำกัด opt-in ให้กับบัญชีเดียวได้:

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

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

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

# พฤติกรรมหมายเลขส่วนตัวและ self-chat

เมื่อหมายเลขตนเองที่เชื่อมโยงอยู่ใน allowFrom ด้วย safeguard ของ self-chat WhatsApp จะเปิดใช้งาน:

• ข้าม read receipt สำหรับรอบ self-chat
• ละเว้นพฤติกรรม auto-trigger ของ mention-JID ที่มิฉะนั้นจะ ping ตัวคุณเอง
• หากไม่ได้ตั้งค่า messages.responsePrefix reply ของ self-chat จะมีค่าเริ่มต้นเป็น [{identity.name}] หรือ [openclaw]

# การ normalize ข้อความและ context

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

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

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

# การส่ง การแบ่งส่วน และสื่อ

# การอ้างอิงในการตอบกลับ

WhatsApp รองรับการอ้างอิงการตอบกลับแบบดั้งเดิม โดยคำตอบขาออกจะอ้างอิงข้อความขาเข้าให้เห็น ควบคุมได้ด้วย channels.whatsapp.replyToMode

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

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

# ระดับการตอบสนอง

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

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

การแทนที่รายบัญชีใช้ 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
      },
    },
  },
}

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

• ส่งทันทีหลังจากขาเข้าได้รับการยอมรับ (ก่อนตอบกลับ)
• ความล้มเหลวจะถูกบันทึกในล็อก แต่ไม่บล็อกการส่งคำตอบตามปกติ
• โหมดกลุ่ม mentions จะตอบสนองในรอบที่ถูกกระตุ้นโดยการกล่าวถึง; การเปิดใช้งานกลุ่ม always ทำหน้าที่เป็นทางลัดข้ามการตรวจสอบนี้
• WhatsApp ใช้ channels.whatsapp.ackReaction (ไม่ได้ใช้ messages.ackReaction แบบเดิมที่นี่)

# หลายบัญชีและข้อมูลประจำตัว

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

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

# การแก้ไขปัญหา

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

# พรอมป์ระบบ

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

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

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

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

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

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

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

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

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

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

# ตัวชี้ไปยังเอกสารอ้างอิงการกำหนดค่า

เอกสารอ้างอิงหลัก:

• เอกสารอ้างอิงการกำหนดค่า - WhatsApp

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

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

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

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