WhatsApp

​

설치(필요 시)

• 온보딩(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

​

빠른 설정

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

​

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

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

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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 확인 반응을 지웁니다.

​

승인 프롬프트

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

​

Plugin 훅과 개인정보 보호

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

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

​

액세스 제어 및 활성화

​

구성된 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 세션으로 팬아웃하지 않습니다.

​

개인 번호 및 자기 채팅 동작

• 자기 채팅 턴의 읽음 확인 건너뛰기
• 자신을 핑하게 될 멘션 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,
        },
      },
    },
  },
}

​

전달, 청킹 및 미디어

​

답장 인용

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

​

반응 수준

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

​

확인 반응

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

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

​

수명 주기 상태 반응

{
  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 whatsapp
openclaw channels status

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

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

시스템 프롬프트

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

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

• 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

• 액세스: 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

​

관련

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