BlueBubbles 채널 설정

BlueBubbles를 통해 macOS iMessage를 OpenClaw와 연동하는 방법을 안내합니다.

개요

BlueBubbles는 macOS에서 iMessage를 다른 플랫폼으로 전달하는 오픈소스 서버입니다:

• macOS 컴퓨터에서 BlueBubbles 서버 실행 필요
• iPhone 없이도 iMessage 수신/발신 가능
• 그룹 채팅, 리액션 지원

요구사항

• macOS 컴퓨터 (항상 켜져 있어야 함)
• Apple ID (iMessage 활성화)
• BlueBubbles 서버 설치

1단계: BlueBubbles 서버 설치

1. bluebubbles.app에서 macOS 서버 다운로드
2. 설치 후 실행
3. Apple ID로 로그인
4. 서버 비밀번호 설정
5. 서버 포트 확인 (기본: 1234)

2단계: OpenClaw 설정

{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://your-mac-ip:1234",
      "password": "your-bb-password"
    }
  }
}

# 환경 변수로 설정 (보안)
export BLUEBUBBLES_URL="http://your-mac-ip:1234"
export BLUEBUBBLES_PASSWORD="your-bb-password"

3단계: 연결 테스트

openclaw gateway start
openclaw channel test --type bluebubbles

접근 제어

특정 연락처만 허용:

{
  "channels": {
    "bluebubbles": {
      "allowedNumbers": ["+821012345678"],
      "allowAll": false
    }
  }
}

트러블슈팅

연결 실패

• macOS 컴퓨터가 켜져 있는지 확인
• 방화벽에서 포트 개방 확인
• BlueBubbles 서버가 실행 중인지 확인

# BlueBubbles 서버 상태 확인
curl http://your-mac-ip:1234/api/v1/ping

메시지가 전송되지 않음

• Apple ID iMessage 활성화 확인
• macOS iMessage 앱에서 로그인 상태 확인

최신 BlueBubbles 업데이트

아웃바운드 전송 타임아웃 설정 (v2026.4.20)

v2026.4.20부터 아웃바운드 텍스트 전송 타임아웃 기본값이 10초에서 30초로 상향되었습니다. macOS 26(Tahoe)에서 Private API iMessage 전송이 60초 이상 걸리는 경우 메시지가 자동 중단(abort)되는 문제를 방지합니다. 탐침(probe), 채팅 조회, 상태 확인은 기존 10초 기본값을 유지합니다 (#69193).

계정별 또는 전역으로 타임아웃을 조정할 수 있습니다:

{
  "channels": {
    "bluebubbles": {
      "sendTimeoutMs": 30000
    }
  }
}

macOS 26(Tahoe) Private API 우선 처리

v2026.4.20부터 macOS 26 환경에서 일반 텍스트 전송 시에도 Private API를 우선 사용합니다. AppleScript 방식의 -1700 오류를 방지합니다.

참고:

• BlueBubbles 공식 사이트
• 공식 문서: BlueBubbles Channel