WhatsApp

상태: WhatsApp Web(Baileys)을 통해 프로덕션 준비 완료. Gateway가 연결된 세션을 소유합니다.

설치(필요 시)

• 온보딩(openclaw onboard)과 openclaw channels add --channel whatsapp는 WhatsApp Plugin을 처음 선택할 때 설치하라는 프롬프트를 표시합니다.
• openclaw channels login --channel whatsapp도 Plugin이 아직 없으면 설치 흐름을 제공합니다.
• Dev 채널 + git 체크아웃: 기본값은 로컬 Plugin 경로입니다.
• Stable/Beta: 먼저 ClawHub에서 공식 @openclaw/whatsapp Plugin을 설치하고, npm을 대체 경로로 사용합니다.
• WhatsApp 런타임은 코어 OpenClaw npm 패키지 외부에서 배포되므로 WhatsApp 전용 런타임 의존성이 외부 Plugin에 남아 있습니다.

수동 설치도 계속 사용할 수 있습니다.

openclaw plugins install clawhub:@openclaw/whatsapp

레지스트리 대체 경로가 필요할 때만 순수 npm 패키지(@openclaw/whatsapp)를 사용하세요. 재현 가능한 설치가 필요할 때만 정확한 버전을 고정하세요.

빠른 설정

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

MeowCaller로 현재 요청자에게 전화 걸기(실험적)

WhatsApp Plugin은 WhatsApp에서 시작된 에이전트 턴에서 whatsapp_call을 노출할 수 있습니다. 이 도구는 MeowCaller를 사용해 현재 승인된 요청자에게 WhatsApp 음성 통화를 걸고, 상대가 응답한 뒤 OpenClaw TTS 메시지를 재생합니다. 이 도구는 대상 번호를 받지 않으므로 프롬프트가 통화를 제3자에게 리디렉션할 수 없습니다. 이 실험적 기능은 기본적으로 비활성화되어 있습니다.

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

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -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"

현재 제한 사항:

• 일대일 발신 오디오 통화만 지원
• 임의의 대상 번호 없음
• 채팅 연결과 인증 공유 없음
• 개인 번호/셀프 채팅 모드에서 자기 자신에게 전화 불가
• 합성 오디오는 60초로 제한
• MeowCaller의 응답/재생/종료 완료 외에 휴대폰 측 청취 가능 여부 수신 확인 없음
• OpenClaw는 MeowCaller의 연결, 응답, 재생, 종료 단계를 포함해 제한된 115~175초 창 이후 동반 프로세스를 중지합니다

배포 패턴

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

런타임 모델

• Gateway가 WhatsApp 소켓과 재연결 루프를 소유합니다.
• 재연결 워치독은 인바운드 앱 메시지 양만이 아니라 WhatsApp Web 전송 활동을 사용하므로, 조용한 연결 기기 세션은 최근에 아무도 메시지를 보내지 않았다는 이유만으로 다시 시작되지 않습니다. 더 긴 애플리케이션 무응답 상한은 전송 프레임이 계속 도착하지만 워치독 창 동안 애플리케이션 메시지가 처리되지 않으면 여전히 재연결을 강제합니다. 최근 활성 세션에 대한 일시적 재연결 후에는 해당 애플리케이션 무응답 확인이 첫 복구 창에 일반 메시지 시간 제한을 사용합니다.
• Baileys 소켓 타이밍은 web.whatsapp.* 아래에 명시됩니다. keepAliveIntervalMs는 WhatsApp Web 애플리케이션 ping을 제어하고, connectTimeoutMs는 시작 핸드셰이크 시간 제한을 제어하며, defaultQueryTimeoutMs는 Baileys 쿼리 대기와 OpenClaw의 로컬 발신 전송/프레즌스 및 인바운드 읽음 확인 작업 한계를 제어합니다.
• 발신 전송에는 대상 계정에 대한 활성 WhatsApp 리스너가 필요합니다.
• 그룹 전송은 텍스트와 미디어 캡션에서 @+<digits> 및 @<digits> 토큰이 LID 기반 그룹을 포함한 현재 WhatsApp 참여자 메타데이터와 일치할 때 네이티브 멘션 메타데이터를 첨부합니다.
• 상태 및 브로드캐스트 채팅은 무시됩니다(@status, @broadcast).
• 재연결 워치독은 인바운드 앱 메시지 양만이 아니라 WhatsApp Web 전송 활동을 따릅니다. 조용한 연결 기기 세션은 전송 프레임이 계속되는 동안 유지되지만, 전송 중단은 이후 원격 연결 해제 경로보다 훨씬 먼저 재연결을 강제합니다.
• 직접 채팅은 DM 세션 규칙을 사용합니다(session.dmScope; 기본값 main은 DM을 에이전트 메인 세션으로 접습니다).
• 그룹 세션은 격리됩니다(agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters는 네이티브 @newsletter JID를 사용하는 명시적 발신 대상이 될 수 있습니다. 발신 뉴스레터 전송은 DM 세션 의미론이 아니라 채널 세션 메타데이터(agent:<agentId>:whatsapp:channel:<jid>)를 사용합니다.
• WhatsApp Web 전송은 Gateway 호스트의 표준 프록시 환경 변수(HTTPS_PROXY, HTTP_PROXY, NO_PROXY / 소문자 변형)를 존중합니다. 채널별 WhatsApp 프록시 설정보다 호스트 수준 프록시 구성을 선호하세요.
• messages.removeAckAfterReply가 활성화되면 OpenClaw는 표시되는 답장이 전달된 후 WhatsApp 확인 반응을 지웁니다.

승인 프롬프트

WhatsApp은 👍 / 👎 반응으로 exec 및 Plugin 승인 프롬프트를 렌더링할 수 있습니다. 전달은 최상위 승인 전달 구성으로 제어됩니다.

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

approvals.exec와 approvals.plugin은 독립적입니다. WhatsApp을 채널로 활성화하는 것은 전송만 연결합니다. 일치하는 승인 계열이 활성화되어 있고 WhatsApp으로 라우팅되지 않는 한 승인 프롬프트를 보내지 않습니다. 세션 모드는 WhatsApp에서 시작된 승인에 대해서만 네이티브 이모지 승인을 전달합니다. 대상 모드는 명시적 WhatsApp 대상에 공유 전달 파이프라인을 사용하며 별도의 승인자 DM 팬아웃을 만들지 않습니다.

WhatsApp 승인 반응에는 allowFrom 또는 "*"의 명시적 WhatsApp 승인자가 필요합니다. defaultTo는 일반 기본 메시지 대상을 제어합니다. 승인 승인자가 아닙니다. 수동 /approve 명령도 승인 해석 전에 일반 WhatsApp 발신자 권한 부여 경로를 통과합니다.

Plugin 훅과 개인정보 보호

WhatsApp 인바운드 메시지에는 개인 메시지 내용, 전화번호, 그룹 식별자, 발신자 이름, 세션 상관관계 필드가 포함될 수 있습니다. 따라서 명시적으로 옵트인하지 않는 한 WhatsApp은 인바운드 message_received 훅 페이로드를 Plugin에 브로드캐스트하지 않습니다.

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

옵트인을 한 계정으로 범위 지정할 수 있습니다.

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

인바운드 WhatsApp 메시지 내용과 식별자를 수신해도 신뢰할 수 있는 Plugin에만 이 설정을 활성화하세요.

액세스 제어 및 활성화

구성된 ACP 바인딩

WhatsApp은 최상위 bindings[] 항목으로 영구 ACP 바인딩을 지원합니다.

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

• 직접 채팅은 +15555550123 같은 E.164 번호와 일치합니다.
• 그룹은 120363424282127706@g.us 같은 WhatsApp 그룹 JID와 일치합니다.
• 그룹 허용 목록, 발신자 정책, 멘션 또는 활성화 게이트는 OpenClaw가 구성된 ACP 세션이 존재하는지 확인하기 전에 실행됩니다.
• 일치한 구성된 ACP 바인딩이 라우트를 소유합니다. WhatsApp 브로드캐스트 그룹은 해당 턴을 일반 WhatsApp 세션으로 팬아웃하지 않습니다.

개인 번호 및 자기 채팅 동작

연결된 자기 번호가 allowFrom에도 있으면 WhatsApp 자기 채팅 보호 장치가 활성화됩니다.

• 자기 채팅 턴의 읽음 확인 건너뛰기
• 자신을 핑하게 될 멘션 JID 자동 트리거 동작 무시
• 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은 아웃바운드 답장이 인바운드 메시지를 눈에 보이게 인용하는 네이티브 답장 인용을 지원합니다. channels.whatsapp.replyToMode로 제어하세요.

기본값은 "off"입니다. 계정별 재정의는 channels.whatsapp.accounts.<id>.replyToMode를 사용합니다.

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

반응 수준

channels.whatsapp.reactionLevel은 에이전트가 WhatsApp에서 이모지 반응을 얼마나 폭넓게 사용하는지 제어합니다.

기본값: "minimal".

계정별 재정의는 channels.whatsapp.accounts.<id>.reactionLevel을 사용합니다.

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

확인 반응

WhatsApp은 channels.whatsapp.ackReaction을 통해 인바운드 수신 시 즉시 확인 반응을 지원합니다. 확인 반응은 reactionLevel에 의해 게이트됩니다. reactionLevel이 "off"이면 억제됩니다.

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

동작 참고 사항:

• 인바운드가 수락된 직후(응답 전)에 전송됩니다.
• ackReaction이 emoji 없이 있으면 WhatsApp은 라우팅된 에이전트의 식별 이모지를 사용하고, 없으면 "👀"로 대체합니다. 확인 반응을 보내지 않으려면 ackReaction을 생략하거나 emoji: ""로 설정하세요.
• 실패는 기록되지만 일반 응답 전달을 차단하지 않습니다.
• 그룹 모드 mentions는 멘션으로 트리거된 턴에 반응합니다. 그룹 활성화 always는 이 검사의 우회로 작동합니다.
• WhatsApp은 channels.whatsapp.ackReaction을 사용합니다(레거시 messages.ackReaction은 여기에서 사용되지 않음).

수명 주기 상태 반응

정적인 수신 확인 이모지를 남기는 대신, 턴 중 WhatsApp이 확인 반응을 교체하도록 하려면 messages.statusReactions.enabled: true를 설정하세요. 활성화하면 OpenClaw는 대기열 등록, 생각 중, 도구 활동, Compaction, 완료, 오류 같은 수명 주기 상태에 동일한 인바운드 메시지 반응 슬롯을 사용합니다.

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

동작 참고 사항:

• channels.whatsapp.ackReaction은 상태 반응이 다이렉트 메시지와 그룹에서 사용 가능한지 여부를 계속 제어합니다.
• 대기열 상태 반응은 일반 확인 반응과 동일한 유효 확인 이모지를 사용합니다.
• WhatsApp은 메시지당 봇 반응 슬롯이 하나이므로, 수명 주기 업데이트는 현재 반응을 제자리에서 교체합니다.
• messages.removeAckAfterReply: true는 구성된 완료/오류 유지 시간이 지난 뒤 최종 상태 반응을 지웁니다.
• 도구 이모지 범주에는 tool, coding, web, deploy, build, concierge가 포함됩니다.

다중 계정 및 자격 증명

도구, 작업 및 구성 쓰기

• 에이전트 도구 지원에는 WhatsApp 반응 작업(react)이 포함됩니다.
• 작업 게이트:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• 채널에서 시작한 구성 쓰기는 기본적으로 활성화됩니다(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은 groups와 direct 맵을 통해 그룹 및 다이렉트 채팅에 Telegram 스타일 시스템 프롬프트를 지원합니다.

그룹 메시지의 해석 계층:

유효한 groups 맵이 먼저 결정됩니다. 계정이 자체 groups를 정의하면 루트 groups 맵을 완전히 대체합니다(깊은 병합 없음). 그런 다음 프롬프트 조회가 결과로 나온 단일 맵에서 실행됩니다.

1. 그룹별 시스템 프롬프트(groups["<groupId>"].systemPrompt): 특정 그룹 항목이 맵에 존재하고 그리고 해당 systemPrompt 키가 정의되어 있을 때 사용됩니다. systemPrompt가 빈 문자열("")이면 와일드카드가 억제되고 시스템 프롬프트가 적용되지 않습니다.
2. 그룹 와일드카드 시스템 프롬프트(groups["*"].systemPrompt): 특정 그룹 항목이 맵에 전혀 없거나, 존재하지만 systemPrompt 키를 정의하지 않을 때 사용됩니다.

다이렉트 메시지의 해석 계층:

유효한 direct 맵이 먼저 결정됩니다. 계정이 자체 direct를 정의하면 루트 direct 맵을 완전히 대체합니다(깊은 병합 없음). 그런 다음 프롬프트 조회가 결과로 나온 단일 맵에서 실행됩니다.

1. 다이렉트별 시스템 프롬프트(direct["<peerId>"].systemPrompt): 특정 피어 항목이 맵에 존재하고 그리고 해당 systemPrompt 키가 정의되어 있을 때 사용됩니다. systemPrompt가 빈 문자열("")이면 와일드카드가 억제되고 시스템 프롬프트가 적용되지 않습니다.
2. 다이렉트 와일드카드 시스템 프롬프트(direct["*"].systemPrompt): 특정 피어 항목이 맵에 전혀 없거나, 존재하지만 systemPrompt 키를 정의하지 않을 때 사용됩니다.

Telegram 다중 계정 동작과의 차이: Telegram에서는 봇이 자신이 속하지 않은 그룹의 그룹 메시지를 받지 않도록 방지하기 위해, 자체 groups를 정의하지 않은 계정까지 포함하여 다중 계정 설정의 모든 계정에서 루트 groups가 의도적으로 억제됩니다. WhatsApp은 이 보호를 적용하지 않습니다. 루트 groups와 루트 direct는 구성된 계정 수와 관계없이 계정 수준 재정의를 정의하지 않은 계정에 항상 상속됩니다. 다중 계정 WhatsApp 설정에서 계정별 그룹 또는 다이렉트 프롬프트를 원하면 루트 수준 기본값에 의존하지 말고 각 계정 아래에 전체 맵을 명시적으로 정의하세요.

중요 동작:

• channels.whatsapp.groups는 그룹별 구성 맵이면서 채팅 수준 그룹 허용 목록입니다. 루트 또는 계정 범위에서 groups["*"]는 해당 범위에 대해 "모든 그룹이 허용됨"을 의미합니다.
• 해당 범위가 이미 모든 그룹을 허용하기를 원할 때만 와일드카드 그룹 systemPrompt를 추가하세요. 여전히 고정된 그룹 ID 집합만 사용 가능하게 하려면 프롬프트 기본값에 groups["*"]를 사용하지 마세요. 대신 명시적으로 허용 목록에 올린 각 그룹 항목에 프롬프트를 반복해서 지정하세요.
• 그룹 허용과 발신자 승인은 별도 검사입니다. groups["*"]는 그룹 처리에 도달할 수 있는 그룹 집합을 넓히지만, 그 자체로 해당 그룹의 모든 발신자를 승인하지는 않습니다. 발신자 접근은 여전히 channels.whatsapp.groupPolicy와 channels.whatsapp.groupAllowFrom으로 별도로 제어됩니다.
• channels.whatsapp.direct는 DM에 동일한 부작용을 갖지 않습니다. direct["*"]는 DM이 dmPolicy와 allowFrom 또는 페어링 저장소 규칙에 의해 이미 허용된 뒤에만 기본 다이렉트 채팅 구성을 제공합니다.

예:

{  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, 계정 수준 재정의
• 운영: 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

관련

• 페어링
• 그룹
• 보안
• 채널 라우팅
• 다중 에이전트 라우팅
• 문제 해결