OpenClaw

OpenClaw BlueBubbles 채널

메시징
보통

BlueBubbles REST API를 통해 OpenClaw를 iMessage에 연결합니다. 이 통합은 Mac을 iMessage 게이트웨이로 전환합니다 — BlueBubbles 서버 앱을 설치하고 Web API를 활성화하면 AI 어시스턴트가 iMessage 메시지, tapback 리액션 및 미디어 첨부 파일을 주고받을 수 있습니다. BlueBubbles는 레거시 imsg CLI를 대체하는 권장 iMessage 채널입니다.

기본 정보
난이도보통
카테고리메시징
지원 기능 수4 / 6

BlueBubbles 지원 기능

텍스트 메시지

지원

미디어 및 파일

지원

리액션

지원

스레드

미지원

음성 메시지

미지원

그룹 채팅

지원

BlueBubbles 사전 요구사항

  • macOS High Sierra (10.13) 이상을 실행하는 Mac (전체 기능을 위해 Ventura 13+ 권장; Tahoe 26은 일부 제한 있음)
  • BlueBubbles 서버 앱 설치됨 (bluebubbles.app에서 다운로드)
  • BlueBubbles 설정에서 Web API 활성화 및 비밀번호 설정 완료
  • OpenClaw Gateway 실행 및 구성 완료

BlueBubbles 빠른 설정

1

Mac에 BlueBubbles 서버 설치

bluebubbles.app/install에서 BlueBubbles 서버 앱을 다운로드하여 설치합니다. 앱을 실행하고 Apple ID로 로그인한 후 초기 설정을 완료합니다. Mac에서 iMessage가 정상적으로 작동하는지 확인하세요.

2

Web API 활성화

BlueBubbles 서버 설정에서 Web/REST API를 활성화하고 강력한 비밀번호를 설정합니다. 서버 URL(예: http://localhost:1234)을 기록해 두세요 — OpenClaw 설정에서 사용합니다.

3

BlueBubbles 채널 구성 추가

'openclaw onboard'를 실행하고 BlueBubbles를 선택하거나, ~/.openclaw/openclaw.json에 serverUrl과 password를 수동으로 추가합니다. 필요에 따라 webhookPath도 설정할 수 있습니다.

4

Webhook 설정 및 테스트

BlueBubbles Webhook을 Gateway로 지정합니다: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>. Gateway를 시작하고 테스트 iMessage를 보내 연결을 확인합니다. pairing 정책을 사용하는 경우 'openclaw pairing approve bluebubbles <code>'로 발신자를 승인합니다.

BlueBubbles 구성 예시

config.json
{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "serverUrl": "http://localhost:1234",
      "password": "YOUR_BLUEBUBBLES_PASSWORD",
      "webhookPath": "/bluebubbles-webhook",
      "dmPolicy": "pairing"
    }
  }
}

BlueBubbles 상세 문서

아키텍처 개요

OpenClaw는 Mac에서 실행되는 BlueBubbles 서버 앱을 통해 iMessage에 연결됩니다. BlueBubbles는 REST API를 노출하며, Gateway는 이 API를 사용하여 메시지 전송, 리액션, 채팅 관리를 수행합니다. 수신 메시지는 Webhook으로 전달됩니다 — BlueBubbles가 새 메시지 이벤트를 Gateway의 Webhook 엔드포인트로 푸시합니다. 아키텍처 흐름: iMessage가 Mac에 도착 → BlueBubbles 서버 → Webhook으로 Gateway에 푸시 → OpenClaw가 AI로 처리 → REST API로 BlueBubbles에 콜백 → iMessage 전달. 이 접근 방식은 상시 온라인 Mac(물리 머신 또는 VM)이 필요합니다. iMessage는 Apple 전용 서비스이기 때문입니다. Mac이 Apple 메시징 생태계와 OpenClaw 어시스턴트 사이의 브리지 역할을 합니다.
전용 Mac Mini 또는 macOS VM이 BlueBubbles를 영구 iMessage 게이트웨이로 운영하기에 이상적입니다.
BlueBubbles는 Private API를 지원하여 tapback 리액션, 메시지 편집, 취소 등의 고급 기능을 제공합니다 — BlueBubbles 설정에서 활성화하세요.

BlueBubbles 서버 설정

BlueBubbles 설정에는 Mac에 서버 앱을 설치해야 합니다: 1. bluebubbles.app/install에서 BlueBubbles를 다운로드하고 앱을 실행. 2. Apple ID로 로그인하고 Mac에서 iMessage가 정상 작동하는지 확인. 3. BlueBubbles 설정에서 Web/REST API 활성화. 4. 강력한 API 비밀번호 설정 — 이 비밀번호로 모든 API 요청과 Webhook 전달을 인증. 5. 앱에 표시되는 서버 URL 기록 (기본값: http://localhost:1234). 6. 선택 사항: Private API를 활성화하여 고급 기능(리액션, 편집, 취소) 사용. 서버는 계속 실행되어야 iMessage 브리지가 작동합니다. 안정성을 위해 BlueBubbles를 시작 시 자동 실행하도록 설정하세요.
webhook URL
# Gateway용 Webhook URL 형식
https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD
BlueBubbles API 비밀번호를 안전하게 보관하세요. 네트워크에 노출된 서버의 경우 BlueBubbles에서 HTTPS를 활성화하고 방화벽 규칙으로 접근을 제한하세요. 동일 호스트 리버스 프록시는 비밀번호 인증을 우회합니다 — 프록시 수준 인증을 추가하고 gateway.trustedProxies를 설정하세요.

DM 정책

DM(다이렉트 메시지) 정책은 iMessage를 통해 AI 어시스턴트와 상호작용할 수 있는 사용자를 제어합니다. OpenClaw는 네 가지 정책을 지원합니다: • pairing (기본값) — 알 수 없는 발신자에게 시간 제한 페어링 코드(1시간 후 만료)가 전송됩니다. 'openclaw pairing approve bluebubbles <CODE>'로 승인 또는 거부합니다. 승인 후 자유롭게 채팅할 수 있습니다. • allowlist — allowFrom 목록에 있는 전화번호와 이메일 주소만 메시지를 보낼 수 있습니다. 나머지는 무시됩니다. 전화번호는 E.164 형식을 지원합니다. • open — 메시지를 보내는 모든 사람에게 응답합니다. 신중하게 사용하세요. • disabled — DM 처리를 완전히 비활성화합니다.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "user@example.com"]
    }
  }
}
allowFrom 필드는 전화번호(E.164 형식, 예: +15551234567)와 이메일 주소를 모두 지원하며 iMessage 라우팅에 사용됩니다.

그룹 채팅 관리

OpenClaw는 BlueBubbles를 통해 iMessage 그룹 채팅을 지원하며 유연한 접근 제어를 제공합니다: • groupPolicy로 그룹 채팅에서 봇을 트리거할 수 있는 사용자를 제어: - open — 모든 그룹 멤버가 상호작용 가능 - allowlist — groupAllowFrom 목록의 주소만 트리거 가능 - disabled (기본값) — 그룹 메시지 무시 • 멘션 감지 — requireMention이 true(그룹 기본값)인 경우 봇은 멘션될 때만 응답합니다. 멘션 패턴은 agents.list[].groupChat.mentionPatterns에서 설정. • 그룹별 설정 — groups 객체로 특정 그룹 채팅에 다른 requireMention 규칙을 설정.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15551234567"],
      "groups": {
        "iMessage;+;chat123456": {
          "requireMention": false
        }
      }
    }
  }
}

iMessage 액션 및 효과

BlueBubbles는 Private API를 통해 풍부한 iMessage 네이티브 액션을 제공합니다. 각 액션은 개별 전환 가능: • reactions — tapback 리액션 송수신 (좋아요, 하트, 싫어요, 웃음, 강조, 물음표) • edit — 전송된 메시지 수정 (macOS 13+ 필요; macOS Tahoe에서 현재 사용 불가) • unsend — 전송된 메시지 취소 (macOS 13+) • reply — GUID를 통한 메시지 스레딩 • sendWithEffect — 버블 효과가 있는 메시지 전송 (슬램, 라우드, 젠틀, 인비저블 잉크 등) • sendAttachment — 미디어 파일 및 음성 메모 전송 (음성은 MP3/CAF 형식; BlueBubbles가 MP3→CAF 변환 자동 처리) 그룹 관리 액션: • renameGroup — 그룹 채팅 이름 변경 • setGroupIcon — 그룹 채팅 사진 설정 (macOS Tahoe에서 불안정) • addParticipant / removeParticipant / leaveGroup — 그룹 멤버 관리
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "actions": {
        "reactions": true,
        "edit": true,
        "unsend": true,
        "reply": true,
        "sendWithEffect": true,
        "sendAttachment": true
      }
    }
  }
}
macOS Tahoe (26)에서 Private API 변경으로 인해 edit 액션이 현재 사용 불가하며, setGroupIcon이 불안정합니다(API는 성공을 반환하지만 아이콘이 동기화되지 않음). Tahoe를 실행 중이라면 이러한 액션을 수동으로 비활성화하세요.

메시지 전달 및 청킹

OpenClaw는 긴 AI 응답에 대해 설정 가능한 청킹 전달을 제공합니다: • textChunkLimit — 메시지 청크당 최대 문자 수 (기본값: 4000). iMessage에는 엄격한 제한이 없지만 너무 긴 메시지는 일부 기기에서 제대로 표시되지 않을 수 있습니다. • chunkMode — 텍스트 분할 방식 제어: - length (기본값) — textChunkLimit 문자 수로 강제 분할 - newline — 단락 경계에서 분할하여 더 자연스러운 읽기 경험 • blockStreaming — true인 경우 응답이 생성되는 동안 블록 단위로 전송되며, 완전한 응답을 기다리지 않습니다. 읽음 확인은 기본적으로 전송되어 자연스러운 대화 느낌을 유지합니다. AI 응답 생성 전후에 타이핑 표시가 자동 전송됩니다.
openclaw.json
{
  "channels": {
    "bluebubbles": {
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "blockStreaming": false,
      "sendReadReceipts": true
    }
  }
}

미디어 및 첨부 파일

BlueBubbles는 iMessage를 통한 미디어 송수신을 지원합니다: • 수신 첨부 파일은 Gateway에 의해 자동으로 다운로드 및 캐시됩니다. 최대 수신 파일 크기는 mediaMaxMb로 제어됩니다 (기본값: 8 MB). • sendAttachment 액션에서 asVoice: true를 설정하여 음성 메모를 전송할 수 있습니다. BlueBubbles는 MP3를 CAF로 자동 변환하여 네이티브 iMessage 음성 메모 재생을 지원합니다. • 발신 미디어는 sendAttachment 액션으로 buffer, filename 및 선택적 mime 타입 매개변수를 사용하여 전송합니다.
음성 메모는 MP3 또는 CAF 형식을 사용하세요. BlueBubbles가 MP3를 CAF로 자동 변환하여 네이티브 iMessage 재생을 지원합니다.
더 큰 첨부 파일을 처리해야 하는 경우 mediaMaxMb를 조정하세요 — 기본값 8 MB는 대부분의 사진과 짧은 동영상을 커버합니다.

메시지 ID 처리

BlueBubbles는 두 가지 유형의 메시지 식별자를 사용합니다: • 짧은 ID — 메모리 내 임시 토큰 (1, 2, 3 등). 빠르지만 일시적입니다. Gateway 재시작이나 캐시 제거 시 만료됩니다. • 전체 ID — 영구적인 프로바이더 식별자 (MessageSidFull, ReplyToIdFull). 재시작 후에도 유지되며 장기 참조에 적합합니다. 액션 매개변수 (messageId, replyTo 등)는 두 형식 모두 허용합니다. 재시작을 넘어 메시지를 참조해야 하는 영구 자동화에는 항상 전체 ID를 사용하세요.
Gateway 재시작 후에도 유효한 자동화에는 전체 메시지 ID를 사용하세요. 짧은 ID는 대화형 사용에 편리하지만 재시작 후 무효화됩니다.

주소 지정 및 라우팅

BlueBubbles는 메시지 전달에 여러 주소 형식을 지원합니다. 안정성 순 우선 라우팅 순서: 1. chat_guid — 가장 안정적인 형식: chat_guid:iMessage;-;+15555550123 2. chat_id — 숫자 채팅 식별자: chat_id:123 3. chat_identifier — 채팅 식별자 문자열 4. 직접 주소 — 전화번호 (+15555550123) 또는 이메일 (user@example.com) 기존 채팅이 없는 직접 주소로 전송할 때 BlueBubbles는 POST /api/v1/chat/new를 통해 자동으로 새 DM을 생성합니다 (Private API 필요).
자동화에서 가장 안정적인 메시지 라우팅을 위해 chat_guid 형식을 사용하세요.

보안 및 Webhook 인증

BlueBubbles는 설정된 비밀번호로 Webhook 전달을 인증합니다. Gateway는 비밀번호 매개변수(쿼리 문자열 또는 헤더를 통해)가 channels.bluebubbles.password 설정과 일치하는지 검증합니다. 보안 고려 사항: • localhost 요청은 자동으로 신뢰되며 비밀번호 검증을 건너뜁니다. • 동일 호스트 리버스 프록시도 비밀번호 검사를 우회합니다 — 동일 머신에서 리버스 프록시를 사용하는 경우 프록시 수준 인증을 추가하고 gateway.trustedProxies를 설정하세요. • BlueBubbles 서버에서 HTTPS를 활성화하여 통신을 암호화. • 방화벽 규칙으로 BlueBubbles API 포트에 대한 외부 접근을 제한. 프로덕션 배포에서는 반드시 HTTPS를 사용하고 Webhook 엔드포인트가 인증 없이 공개되지 않도록 하세요.
동일 호스트 리버스 프록시는 BlueBubbles 비밀번호 인증을 우회합니다. 리버스 프록시 사용 시 반드시 프록시 수준 인증을 설정하고 gateway.trustedProxies를 구성하세요.

Messages.app 킵얼라이브 (헤드리스/VM)

헤드리스 Mac이나 VM에서 BlueBubbles를 실행하는 경우 Messages.app가 유휴 상태가 되어 메시지 처리를 중단할 수 있습니다. 해결책은 5분마다 AppleScript를 실행하여 Messages 스크립팅 인터페이스를 터치하는 LaunchAgent를 설정하는 것입니다. 이 킵얼라이브 스크립트는 일시적인 오류를 안전하게 무시하고 다른 애플리케이션의 포커스를 빼앗지 않습니다. iMessage 브리지의 안정적인 무인 운영에 필수적입니다. macOS LaunchAgent plist를 설정하여 정기적으로 AppleScript를 실행하고 Messages.app의 응답성을 유지하세요.
이것은 헤드리스/VM 환경에서만 필요합니다. Mac에 활성 데스크톱 세션이 있고 Messages.app가 보이는 경우 킵얼라이브는 필요 없습니다.
launchctl로 LaunchAgent를 관리하세요 — 부팅 시 로드하여 완전한 무인 운영을 실현합니다.

BlueBubbles 구성 참조

enabled
Type: booleanDefault: false

BlueBubbles 채널 활성화/비활성화

serverUrl
Type: stringDefault: ""

BlueBubbles REST API 기본 URL (예: http://localhost:1234)

password
Type: stringDefault: ""

인증용 BlueBubbles API 비밀번호

webhookPath
Type: stringDefault: "/bluebubbles-webhook"

수신 메시지용 Webhook 엔드포인트 경로

dmPolicy
Type: stringDefault: "pairing"

봇에 DM할 수 있는 사용자 제어. 옵션: pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

메시지 전송이 허용된 전화번호 및 이메일 (전화번호는 E.164 형식)

groupPolicy
Type: stringDefault: "allowlist"

그룹 채팅 정책. 옵션: open, allowlist, disabled

groupAllowFrom
Type: string[]Default: []

그룹 채팅에서 봇을 트리거할 권한이 있는 발신자 주소

sendReadReceipts
Type: booleanDefault: true

메시지 처리 시 읽음 확인 전송

blockStreaming
Type: booleanDefault: false

완전한 응답 대기 대신 블록 기반 응답 스트리밍 활성화

textChunkLimit
Type: numberDefault: 4000

발신 텍스트 메시지 청크당 최대 문자 수

chunkMode
Type: stringDefault: "length"

텍스트 분할 모드. 옵션: length (크기 기반), newline (단락 기반)

mediaMaxMb
Type: numberDefault: 8

수신 첨부 파일의 최대 파일 크기 (MB)

historyLimit
Type: numberDefault: -

AI 컨텍스트로 포함할 최대 그룹 메시지 수 (0은 비활성화)

dmHistoryLimit
Type: numberDefault: -

AI 컨텍스트의 DM 대화 기록 제한

actions.reactions
Type: booleanDefault: true

tapback 리액션 활성화 (Private API 필요)

actions.edit
Type: booleanDefault: true

메시지 편집 활성화 (macOS 13+ 필요; Tahoe에서 사용 불가)

actions.unsend
Type: booleanDefault: true

메시지 취소 활성화 (macOS 13+ 필요)

actions.reply
Type: booleanDefault: true

GUID를 통한 메시지 스레딩 활성화

actions.sendWithEffect
Type: booleanDefault: true

iMessage 버블 효과 활성화 (슬램, 라우드, 젠틀 등)

actions.sendAttachment
Type: booleanDefault: true

미디어 및 음성 메모 전달 활성화

BlueBubbles 자주 묻는 질문

BlueBubbles 문제 해결

Webhook이 메시지를 수신하지 않음

BlueBubbles의 Webhook URL이 Gateway 엔드포인트와 일치하지 않거나 비밀번호 매개변수가 올바르지 않음.

Webhook URL이 https://your-gateway-host:3000/bluebubbles-webhook?password=YOUR_PASSWORD로 설정되었는지 확인. channels.bluebubbles.webhookPath가 URL의 경로와 일치하는지 확인. Gateway 로그에서 수신 Webhook 요청을 확인.
Gateway는 연결되었지만 액션이 실패함 (리액션, 편집, 취소)

BlueBubbles Private API가 활성화되지 않았거나 서버 버전이 필요한 API 엔드포인트를 지원하지 않음.

BlueBubbles 서버 설정에서 Private API를 활성화. BlueBubbles를 최신 버전으로 업데이트. 특정 액션이 macOS Tahoe에서 실패하면 개별적으로 비활성화: channels.bluebubbles.actions.edit=false.
헤드리스 Mac에서 Messages.app가 응답하지 않음

Messages.app가 헤드리스/VM 환경에서 유휴 상태가 되어 스크립팅 인터페이스 처리를 중단.

AppleScript 킵얼라이브 LaunchAgent를 설정하여 5분마다 Messages 스크립팅 인터페이스를 터치. LaunchAgent가 launchctl로 로드되고 부팅 시 실행되는지 확인.
봇이 보낸 메시지가 iMessage가 아님 (녹색 말풍선)

수신자의 전화번호나 이메일이 iMessage에 등록되지 않았거나 Mac의 Apple ID에서 iMessage가 비활성화됨.

Mac의 Messages.app 환경설정에서 iMessage가 활성화되었는지 확인. 수신자가 iMessage가 활성화된 Apple 기기를 사용하는지 확인. 녹색 말풍선은 SMS 폴백을 나타내며 BlueBubbles는 설정에 따라 지원하지 않을 수 있습니다.
macOS Tahoe에서 편집 액션 실패

알려진 문제 — macOS Tahoe (26)가 메시지 편집의 Private API 엔드포인트를 손상.

편집 액션 비활성화: channels.bluebubbles.actions.edit를 false로 설정. 이것은 Tahoe에서의 알려진 BlueBubbles 제한입니다. 수정 사항은 BlueBubbles 릴리스를 주시하세요.
전체 문서 보기모든 채널로 돌아가기

관련 채널

WhatsApp

Medium

OpenClaw Baileys 프로토콜을 사용한 QR 코드 연결

설정 가이드

Telegram

Easy

OpenClaw grammY 프레임워크를 통한 Bot API 통합

설정 가이드

Discord

Easy

OpenClaw discord.js를 사용한 Bot Token 통합

설정 가이드