WhatsApp

상태: WhatsApp Web(Baileys)을 통해 프로덕션에서 사용할 수 있습니다. Gateway가 연결된 세션을 소유하며, 별도의 Twilio WhatsApp 채널은 없습니다.

설치

openclaw onboard와 openclaw channels add --channel whatsapp는 처음 선택할 때 Plugin 설치를 안내합니다. Plugin이 없으면 openclaw channels login --channel whatsapp도 동일한 설치 절차를 제공합니다. 개발 체크아웃은 로컬 Plugin 경로를 사용하며, 안정/베타 설치에서는 먼저 ClawHub에서 @openclaw/whatsapp를 설치하고 실패하면 npm으로 대체합니다. WhatsApp 런타임은 핵심 OpenClaw npm 패키지 외부에서 제공되므로 런타임 종속성은 외부 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>

배포 패턴

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

런타임 모델

• Gateway가 WhatsApp 소켓과 재연결 루프를 소유합니다.
• 감시자는 원시 WhatsApp Web 전송 활동과 애플리케이션 메시지 활동이라는 두 신호를 독립적으로 추적합니다. 연결은 유지되지만 조용한 세션은 최근 메시지가 도착하지 않았다는 이유만으로 재시작되지 않습니다. 전송 프레임이 고정된 내부 시간 범위(사용자가 구성할 수 없음) 동안 도착하지 않거나 애플리케이션 메시지가 일반 메시지 제한 시간의 4배를 넘도록 수신되지 않을 때만 강제로 재연결합니다. 최근 활성 상태였던 세션을 재연결한 직후의 첫 번째 시간 범위에는 4배 시간 범위 대신 더 짧은 일반 메시지 제한 시간을 사용합니다. Baileys가 해당 재연결 초기에 전달하는 오프라인 메시지에 OpenClaw가 자동 응답할 수 있으며, 이는 수신 메시지 ID 중복 제거 수명으로 제한됩니다. 최초 시작 시에는 짧은 이전 기록 차단 규칙이 유지됩니다.
• Baileys 소켓 타이밍은 web.whatsapp.* 아래에 명시적으로 구성됩니다. keepAliveIntervalMs(애플리케이션 핑 간격), connectTimeoutMs(연결 핸드셰이크 제한 시간), defaultQueryTimeoutMs(Baileys 쿼리 대기 시간과 OpenClaw의 발신 전송/상태 표시 및 수신 읽음 확인 제한 시간)입니다.
• 발신 전송에는 대상 계정에 활성 WhatsApp 리스너가 필요하며, 그렇지 않으면 즉시 실패합니다.
• 그룹 전송은 @+<digits> 및 @<digits> 토큰(텍스트와 미디어 캡션 내)이 LID 기반 그룹을 포함한 현재 참여자 메타데이터와 일치할 때 네이티브 멘션 메타데이터를 첨부합니다.
• 상태 및 브로드캐스트 채팅(@status, @broadcast)은 무시됩니다.
• 직접 채팅은 DM 세션 규칙(session.dmScope; 기본값 main은 DM을 에이전트 기본 세션으로 통합)을 사용합니다. 그룹 세션은 JID별로 격리됩니다(agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp 채널/뉴스레터는 네이티브 @newsletter JID를 통해 명시적인 발신 대상으로 지정할 수 있으며, DM 의미 체계 대신 채널 세션 메타데이터(agent:<agentId>:whatsapp:channel:<jid>)를 사용합니다.
• WhatsApp Web 전송은 Gateway 호스트의 표준 프록시 환경 변수(HTTPS_PROXY, HTTP_PROXY, NO_PROXY 및 소문자 변형)를 따릅니다. 채널별 설정보다 호스트 수준의 프록시 구성을 권장합니다.
• messages.removeAckAfterReply가 활성화된 경우 OpenClaw는 표시되는 응답이 전달된 후 확인 반응을 제거합니다.

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

Plugin은 WhatsApp에서 시작된 에이전트 턴에 whatsapp_call을 노출할 수 있습니다. MeowCaller를 사용하여 현재 승인된 요청자에게 WhatsApp 음성 통화를 걸고, 상대방이 응답하면 OpenClaw TTS 메시지를 재생합니다. 이 도구에는 대상 전화번호 매개변수가 없으므로 프롬프트가 통화를 다른 곳으로 전환할 수 없습니다. 기본적으로 비활성화되어 있습니다.

{"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는 제한된 115~175초 시간 범위(MeowCaller의 연결, 응답, 재생 및 종료 단계 포함) 후 보조 프로세스를 중지합니다.

승인 프롬프트

WhatsApp은 최상위 승인 전달 구성에 따라 실행 및 Plugin 승인 프롬프트를 👍/👎 반응으로 표시할 수 있습니다.

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

approvals.exec와 approvals.plugin은 서로 독립적입니다. WhatsApp을 채널로 활성화하면 전송 계층만 연결되며, 해당 승인 종류가 활성화되고 WhatsApp으로 라우팅되지 않는 한 아무것도 전송하지 않습니다. 세션 모드는 WhatsApp에서 시작된 승인에만 네이티브 이모지 승인을 전달합니다. 대상 모드는 명시적 대상에 공유 전달 파이프라인을 사용하며 별도의 승인자 DM 전파를 생성하지 않습니다.

WhatsApp 승인 반응을 사용하려면 allowFrom에 승인자를 명시적으로 지정해야 합니다(또는 "*" 사용). defaultTo는 일반적인 기본 메시지 대상을 설정하며 승인자 목록이 아닙니다. 수동 /approve 명령도 승인 처리 전에 일반적인 WhatsApp 발신자 승인 경로를 통과합니다.

Plugin 후크 및 개인정보 보호

수신 WhatsApp 메시지에는 개인 콘텐츠, 전화번호, 그룹 식별자, 발신자 이름 및 세션 상관관계 필드가 포함될 수 있습니다. 사용자가 명시적으로 동의하지 않는 한 WhatsApp은 수신 message_received 후크 페이로드를 Plugin에 브로드캐스트하지 않습니다.

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

channels.whatsapp.accounts.<id>.pluginHooks.messageReceived 아래에서 하나의 계정에만 동의 범위를 지정하세요. 수신 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" },      },    },  ],}

직접 채팅은 E.164 번호와 일치하고, 그룹은 WhatsApp 그룹 JID와 일치합니다. 그룹 허용 목록, 발신자 정책 및 멘션/활성화 제한은 OpenClaw가 바인딩된 ACP 세션의 존재를 보장하기 전에 실행됩니다. 일치한 바인딩이 경로를 소유하므로 브로드캐스트 그룹은 해당 턴을 일반 WhatsApp 세션으로 분산하지 않습니다.

개인 번호 및 자기 채팅 동작

연결된 본인 번호가 allowFrom에도 포함되어 있으면 자기 채팅 안전장치가 활성화됩니다. 자기 채팅 턴의 읽음 확인을 건너뛰고, 자신에게 알림을 보내게 되는 멘션 JID 자동 트리거 동작을 무시하며, messages.responsePrefix가 설정되지 않은 경우 답장의 기본 접두사를 [{identity.name}](또는 [openclaw])로 지정합니다.

메시지 정규화 및 컨텍스트

[<sender>에게 답장 중 id:<stanzaId>]<인용된 본문 또는 미디어 자리표시자>[/답장 중]

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

전송, 분할 및 미디어

답장 인용

channels.whatsapp.replyToMode는 네이티브 답장 인용을 제어합니다(발신 답장에 수신 메시지가 눈에 보이게 인용됨).

계정별 재정의: channels.whatsapp.accounts.<id>.replyToMode.

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

반응 수준

channels.whatsapp.reactionLevel은 에이전트가 이모지 반응을 사용하는 범위를 제어합니다.

계정별 재정의: channels.whatsapp.accounts.<id>.reactionLevel.

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

확인 반응

channels.whatsapp.ackReaction은 수신 즉시 반응을 전송하며 reactionLevel의 제한을 받습니다("off"이면 억제됨).

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

참고: 수신이 수락된 직후(답장 전)에 전송됩니다. ackReaction이 있지만 emoji가 없으면 WhatsApp은 라우팅된 에이전트의 ID 이모지를 사용하고, 없으면 "👀"을 사용합니다(확인 반응을 사용하지 않으려면 ackReaction을 생략하거나 emoji: ""로 설정). 실패는 로그에 기록되지만 답장 전송을 차단하지 않습니다. 그룹 모드 mentions는 멘션으로 트리거된 턴에만 반응하지만 그룹 활성화 always는 이 검사를 우회합니다. WhatsApp은 channels.whatsapp.ackReaction만 사용하며 레거시 messages.ackReaction은 여기에 적용되지 않습니다.

수명 주기 상태 반응

messages.statusReactions.enabled: true로 설정하면 WhatsApp이 턴 중 정적인 수신 이모지를 그대로 두는 대신 확인 반응을 교체하며 대기열, 생각 중, 도구 활동, 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(기존 작업의 기본값은 true), channels.whatsapp.actions.calls(기본값은 false, 위의 MeowCaller 참조).
• 채널에서 시작된 구성 쓰기는 기본적으로 활성화됩니다. 비활성화하려면 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 키가 정의된 경우 사용됩니다. 빈 문자열("")은 와일드카드를 억제하고 프롬프트를 적용하지 않습니다.
2. 그룹 와일드카드 프롬프트(groups["*"].systemPrompt): 특정 그룹 항목이 없거나, 항목은 있지만 systemPrompt 키가 없는 경우 사용됩니다.

직접 메시지는 direct 맵 및 direct["*"]에 대해 동일한 패턴으로 해석됩니다.

Telegram과의 차이점: Telegram은 다중 계정 설정에서 봇이 속하지 않은 그룹의 그룹 메시지를 수신하지 않도록 모든 계정에 대해 루트 groups를 억제합니다(자체 groups가 없는 계정도 포함). WhatsApp은 이 보호 장치를 적용하지 않습니다. 자체 재정의가 없는 모든 계정은 계정 수와 관계없이 루트 groups/direct를 상속합니다. 다중 계정 WhatsApp 설정에서 계정별 프롬프트를 사용하려면 각 계정 아래에 전체 맵을 명시적으로 정의합니다.

중요 동작:

• channels.whatsapp.groups는 그룹별 구성 맵이자 채팅 수준의 그룹 허용 목록입니다. 루트 또는 계정 범위에서 groups["*"]는 해당 범위에 대해 "모든 그룹 허용"을 의미합니다.
• 해당 범위에서 이미 모든 그룹을 허용하려는 경우에만 와일드카드 systemPrompt를 추가합니다. 고정된 그룹 ID 집합만 허용하려면 groups["*"]를 사용하는 대신 명시적으로 허용 목록에 추가한 각 항목에 프롬프트를 반복해서 지정합니다.
• 그룹 허용과 발신자 권한 부여는 별도의 검사입니다. groups["*"]는 그룹 처리에 도달하는 그룹의 범위를 넓히지만, 해당 그룹의 모든 발신자에게 권한을 부여하지는 않습니다. 이는 계속 groupPolicy/groupAllowFrom으로 제어됩니다.
• channels.whatsapp.direct는 DM에 대해 이와 같은 부수 효과가 없습니다. direct["*"]는 DM이 dmPolicy와 allowFrom 또는 페어링 저장소 규칙에 의해 이미 허용된 후에만 기본 구성을 제공합니다.

예시:

{  channels: {    whatsapp: {      groups: {        // 루트 범위에서 모든 그룹을 허용해야 하는 경우에만 사용합니다.        // 자체 groups 맵을 정의하지 않은 모든 계정에 적용됩니다.        "*": { systemPrompt: "모든 그룹의 기본 프롬프트입니다." },      },      direct: {        // 자체 direct 맵을 정의하지 않은 모든 계정에 적용됩니다.        "*": { systemPrompt: "모든 직접 채팅의 기본 프롬프트입니다." },      },      accounts: {        work: {          groups: {            // 이 계정은 자체 groups를 정의하므로 루트 groups가 완전히            // 대체됩니다. 와일드카드를 유지하려면 여기에도 "*"를 명시적으로 정의합니다.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "프로젝트 관리에 집중합니다.",            },            // 이 계정에서 모든 그룹을 허용해야 하는 경우에만 사용합니다.            "*": { systemPrompt: "업무 그룹의 기본 프롬프트입니다." },          },          direct: {            // 이 계정은 자체 direct 맵을 정의하므로 루트 direct 항목이            // 완전히 대체됩니다. 와일드카드를 유지하려면 여기에도 "*"를 명시적으로 정의합니다.            "+15551234567": { systemPrompt: "특정 업무 직접 채팅의 프롬프트입니다." },            "*": { systemPrompt: "업무 직접 채팅의 기본 프롬프트입니다." },          },        },      },    },  },}

구성 참조 안내

기본 참조: 구성 참조 - WhatsApp

관련 문서

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