BlueBubbles를 통해 OpenClaw을 iMessage에 연결하기

BlueBubbles를 선택하는 이유

이전에 OpenClaw의 네이티브 iMessage 통합(AppleScript 브릿지 기반)을 사용했다면, 폴링 지연, 리치 미디어 전송 불가, macOS 시스템 업데이트에 민감한 문제 등 여러 제약이 있었을 것입니다. OpenClaw 최신 버전부터 기존 iMessage 통합은 공식적으로 deprecated 되었으며, iMessage 연결의 대안으로 BlueBubbles를 공식 권장합니다.

BlueBubbles는 오픈소스 프로젝트로, macOS에서 서버를 실행하고 REST API를 통해 iMessage의 완전한 기능을 제공합니다. OpenClaw은 이 API를 통해 iMessage와 상호작용하며, 기존 방안에 비해 다음과 같은 뚜렷한 장점이 있습니다:

REST API 아키텍처: 안정적이고 신뢰할 수 있으며, 취약한 AppleScript 브릿지에 더 이상 의존하지 않음
완전한 기능 지원: 텍스트, 이미지, 첨부 파일, Tapback 반응 등의 수신 및 발송
실시간 메시지 푸시: WebSocket을 통한 즉각적인 알림, 폴링 지연 해소
네이티브 통합: OpenClaw에 BlueBubbles 채널 지원이 내장되어 추가 플러그인 불필요
활발한 유지보수: BlueBubbles 커뮤니티가 활발하며, macOS 업데이트를 지속적으로 추적

사전 조건

시작하기 전에 다음 준비를 확인하세요:

조건	요구사항
macOS 기기	BlueBubbles 서버용 Mac 1대 (Mac mini 권장)
macOS 버전	macOS 11 Big Sur 이상
Apple ID	iMessage에 로그인된 Apple ID
OpenClaw	설치 및 정상 실행 중 (Mac과 같은 기기일 필요 없음)
네트워크	BlueBubbles 서버에 OpenClaw이 접근 가능해야 함

기존 방안과 달리, OpenClaw 자체는 macOS에서 실행할 필요가 없습니다. Linux VPS에서 OpenClaw을 실행하면서 Mac mini를 BlueBubbles 서버로 사용할 수 있습니다. 이러한 분리 아키텍처가 더 유연합니다.

1단계: BlueBubbles 서버 설치 및 설정

1.1 BlueBubbles 다운로드

BlueBubbles 공식 웹사이트에서 macOS 서버 앱을 다운로드하거나 Homebrew로 설치합니다:

brew install --cask bluebubbles

1.2 초기 설정

BlueBubbles를 처음 시작한 후 가이드에 따라 기본 설정을 완료합니다:

BlueBubbles에 전체 디스크 접근 권한을 부여합니다 (시스템 설정 → 개인정보 보호 및 보안 → 전체 디스크 접근 권한)
Messages.app에 Apple ID가 로그인되어 있는지 확인합니다
BlueBubbles에서 서버 비밀번호를 설정합니다 (이후 OpenClaw 설정에 입력 필요)

1.3 REST API 주소 확인

BlueBubbles가 시작되면 상태 표시줄에 서버의 로컬 주소가 표시됩니다. 보통 다음과 같습니다:

http://localhost:1234

OpenClaw이 다른 기기에서 실행되는 경우, 이 포트가 원격으로 접근 가능해야 합니다. 다음 방법으로 구현할 수 있습니다:

LAN 직접 연결: 두 기기가 같은 네트워크에 있는지 확인하고, Mac의 LAN IP 사용
리버스 프록시: Nginx 또는 Cloudflare Tunnel을 사용하여 API 노출
BlueBubbles 내장 Ngrok/동적 DNS 기능

2단계: OpenClaw에서 BlueBubbles 연결 설정

2.1 채널 추가

다음 명령으로 BlueBubbles 채널을 추가합니다:

openclaw channel add bluebubbles

가이드가 BlueBubbles 서버 주소와 비밀번호를 입력하도록 안내합니다.

2.2 수동 설정 편집

~/.config/openclaw/openclaw.json5를 직접 편집할 수도 있습니다:

{
  channels: {
    bluebubbles: {
      enabled: true,

      // BlueBubbles 서버 주소
      serverUrl: "http://192.168.1.100:1234",

      // BlueBubbles 서버 비밀번호
      password: "your-server-password",

      // 보안 설정
      security: {
        allowedIdentifiers: [
          "+8613800138000",
          "[email protected]"
        ],
        groupChatEnabled: false,
        allowUnknown: false
      },

      // 트리거 설정
      trigger: {
        autoReply: true,
        keywords: [],
        groupTrigger: "keyword",
        groupKeywords: ["@AI", "/ask"]
      },

      // 메시지 설정
      message: {
        maxLength: 10000,
        sendTypingIndicator: true,
        sendReadReceipts: true,
        supportAttachments: true
      }
    }
  }
}

2.3 시작 및 검증

openclaw restart

# BlueBubbles 채널 로그 확인
openclaw logs -f --component channel:bluebubbles

연결 성공 시 다음과 같이 표시됩니다:

[INFO] [channel:bluebubbles] BlueBubbles 연결이 수립되었습니다
[INFO] [channel:bluebubbles] 서버 버전: 1.x.x
[INFO] [channel:bluebubbles] WebSocket 연결됨, 실시간 메시지 대기 중...
[INFO] [channel:bluebubbles] 허용된 연락처: 2개

기존 iMessage 통합에서 마이그레이션

이전에 기존 AppleScript 방안을 사용했다면, 마이그레이션 단계는 간단합니다:

OpenClaw 서비스 중지: openclaw stop
설정 파일에서 channels.imessage.enabled를 false로 변경
위의 단계에 따라 BlueBubbles 채널 설정
재시작: openclaw up

기존 imessage 채널 설정은 설정 파일에 그대로 유지할 수 있으며, enabled가 false인지만 확인하면 됩니다. OpenClaw은 시작 시 기존 iMessage 채널이 여전히 활성화되어 있으면 deprecated 경고를 출력하고 BlueBubbles로 전환을 권장합니다.

메시지 유형 지원 비교

BlueBubbles 방안은 기존 방안 대비 대폭 향상되었습니다:

메시지 유형	기존 iMessage	BlueBubbles
텍스트 수발신	지원	지원
이미지 수신	부분	완전 지원
이미지 발송	미지원	지원
첨부 파일 수발신	미지원	지원
Tapback 반응	미지원	지원
읽음 확인	미지원	지원
입력 표시	미지원	지원
그룹 관리	미지원	지원
실시간 푸시	미지원 (폴링)	지원 (WebSocket)

자주 발생하는 문제 해결

BlueBubbles 서버에 연결할 수 없는 경우

# 네트워크 연결성 테스트
curl http://192.168.1.100:1234/api/v1/server/info -H "Authorization: Bearer your-password"

서버 정보 JSON이 반환되면 네트워크와 인증 모두 정상입니다. 그렇지 않으면 방화벽 설정과 비밀번호가 올바른지 확인하세요.

Mac 잠자기로 인한 연결 끊김

서버로 사용하는 Mac은 잠자기 모드에 진입해서는 안 됩니다. 시스템 설정에서 자동 잠자기를 해제합니다:

시스템 설정 → 에너지 절약 → 자동 잠자기 방지

Mac mini의 경우, 디스플레이를 연결하거나 HDMI 더미 플러그를 사용하여 시스템이 디스플레이 없이 성능을 저하시키는 것을 방지하는 것을 권장합니다.

BlueBubbles 업데이트 후 연결 이상

BlueBubbles 업데이트로 API 동작이 변경될 수 있습니다. 이 경우 OpenClaw도 최신 버전으로 업데이트하세요:

openclaw update
openclaw restart

정리

BlueBubbles는 OpenClaw이 공식 권장하는 iMessage 연결 방안으로, deprecated된 기존 AppleScript 통합을 완전히 대체합니다. REST API와 WebSocket을 통해 안정적이고 기능이 완전한 iMessage 연결 경험을 제공합니다. 핵심 요점:

반드시 마이그레이션하세요: 기존 iMessage 통합은 deprecated 되었으며 향후 버전에서 제거될 수 있습니다
유연한 아키텍처: OpenClaw과 BlueBubbles 서버를 분리 배포 가능
완전한 기능: 이미지, 첨부 파일, Tapback, 읽음 확인 등 완전한 기능 지원
화이트리스트 설정: 다른 채널과 마찬가지로 연락처 화이트리스트를 설정하여 개인정보와 API 한도를 보호하세요
Mac 항상 켜기: BlueBubbles를 실행하는 Mac이 잠자기나 종료되지 않도록 하세요