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배 범위 대신 더 짧은 일반 메시지 제한 시간을 사용합니다. OpenClaw는 해당 재연결 초기에 Baileys가 전달하는 오프라인 메시지에 자동으로 응답할 수 있으며, 이는 수신 메시지 ID 중복 제거 수명으로 제한됩니다. 최초 시작 시에는 짧은 이전 기록 차단 규칙이 유지됩니다.
• Baileys 소켓 타이밍은 web.whatsapp.* 아래에 명시되어 있습니다. keepAliveIntervalMs(애플리케이션 핑 간격), connectTimeoutMs(연결 시작 핸드셰이크 제한 시간), defaultQueryTimeoutMs(Baileys 쿼리 대기 시간과 OpenClaw의 송신 전송/프레즌스 및 수신 읽음 확인 제한 시간)입니다.
• 송신 전송에는 대상 계정의 활성 WhatsApp 리스너가 필요하며, 그렇지 않으면 전송이 즉시 실패합니다.
• 그룹 전송은 토큰이 LID 기반 그룹을 포함한 현재 참여자 메타데이터와 일치할 때 @+<digits> 및 @<digits> 토큰(텍스트 및 미디어 캡션)에 네이티브 멘션 메타데이터를 첨부합니다.
• 상태 및 브로드캐스트 채팅(@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은 최상위 승인 전달 구성에 따라 exec 및 Plugin 승인 프롬프트를 👍/👎 반응으로 표시할 수 있습니다.

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

approvals.exec과 approvals.plugin은 서로 독립적입니다. 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])으로 지정합니다.

메시지 정규화 및 컨텍스트

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

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

참고: 수신이 허용된 직후(답장 전)에 전송됩니다. emoji 없이 ackReaction이 있으면 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

관련 문서

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