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.

​

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

• 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

winget install --id Git.Git -e

​

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

{
  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 และความเป็นส่วนตัว

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

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

​

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

​

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

• ข้าม 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,
        },
      },
    },
  },
}

​

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

​

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

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

​

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

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

​

การตอบสนองเพื่อรับทราบ

{
  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

​

พรอมป์ระบบ

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

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

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

• การเข้าถึง: 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

​

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

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