​

BlueBubbles (macOS REST)

​

번들 plugin

​

개요

• BlueBubbles helper 앱(bluebubbles.app)을 통해 macOS에서 실행됩니다.
• 권장/테스트 환경: macOS Sequoia (15). macOS Tahoe (26)에서도 작동하지만, 현재 Tahoe에서는 편집 기능이 깨져 있으며 그룹 아이콘 업데이트는 성공으로 표시되더라도 동기화되지 않을 수 있습니다.
• OpenClaw는 REST API(GET /api/v1/ping, POST /message/text, POST /chat/:id/*)를 통해 통신합니다.
• 수신 메시지는 웹훅으로 도착하며, 발신 답장, 타이핑 표시기, 읽음 확인, 탭백은 REST 호출로 처리됩니다.
• 첨부파일과 스티커는 수신 미디어로 수집되며(가능한 경우 에이전트에 표시됨).
• 페어링/허용 목록은 다른 채널과 동일한 방식으로 작동하며( /channels/pairing 등), channels.bluebubbles.allowFrom + 페어링 코드를 사용합니다.
• 반응은 Slack/Telegram과 마찬가지로 시스템 이벤트로 표시되므로, 에이전트는 답장 전에 이를 “언급”할 수 있습니다.
• 고급 기능: 편집, 전송 취소, 답장 스레딩, 메시지 효과, 그룹 관리.

​

빠른 시작

1. Mac에 BlueBubbles 서버를 설치합니다(bluebubbles.app/install의 안내를 따르세요).
2. BlueBubbles 설정에서 웹 API를 활성화하고 비밀번호를 설정합니다.
3. openclaw onboard를 실행하고 BlueBubbles를 선택하거나, 수동으로 구성합니다:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         serverUrl: "http://192.168.1.100:1234",
         password: "example-password",
         webhookPath: "/bluebubbles-webhook",
       },
     },
   }
   
4. BlueBubbles 웹훅이 게이트웨이를 가리키도록 설정합니다(예: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>).
5. 게이트웨이를 시작하면 웹훅 핸들러를 등록하고 페어링을 시작합니다.

• 항상 웹훅 비밀번호를 설정하세요.
• 웹훅 인증은 항상 필요합니다. OpenClaw는 루프백/프록시 토폴로지와 관계없이 channels.bluebubbles.password와 일치하는 비밀번호/guid를 포함하지 않는 BlueBubbles 웹훅 요청을 거부합니다(예: ?password=<password> 또는 x-password).
• 비밀번호 인증은 전체 웹훅 본문을 읽거나 파싱하기 전에 검사됩니다.

​

Messages.app 활성 상태 유지하기(VM / 헤드리스 설정)

​

1) AppleScript 저장

• ~/Scripts/poke-messages.scpt

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

​

2) LaunchAgent 설치

• ~/Library/LaunchAgents/com.user.poke-messages.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

• 이는 300초마다 그리고 로그인 시 실행됩니다.
• 첫 실행 시 macOS Automation 프롬프트(osascript → Messages)가 나타날 수 있습니다. LaunchAgent를 실행하는 동일한 사용자 세션에서 이를 승인하세요.

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

​

온보딩

openclaw onboard

• Server URL (필수): BlueBubbles 서버 주소(예: http://192.168.1.100:1234)
• Password (필수): BlueBubbles Server 설정의 API 비밀번호
• Webhook path (선택 사항): 기본값은 /bluebubbles-webhook
• DM policy: pairing, allowlist, open, 또는 disabled
• Allow list: 전화번호, 이메일 또는 채팅 대상

openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

​

접근 제어(DM + 그룹)

• 기본값: channels.bluebubbles.dmPolicy = "pairing".
• 알 수 없는 발신자에게는 페어링 코드가 전송되며, 승인될 때까지 메시지는 무시됩니다(코드는 1시간 후 만료).
• 다음으로 승인:
  • openclaw pairing list bluebubbles
  • openclaw pairing approve bluebubbles <CODE>
• 페어링이 기본 토큰 교환 방식입니다. 자세한 내용: 페어링

• channels.bluebubbles.groupPolicy = open | allowlist | disabled (기본값: allowlist).
• channels.bluebubbles.groupAllowFrom은 allowlist가 설정된 경우 그룹에서 누가 트리거할 수 있는지 제어합니다.

​

연락처 이름 보강(macOS, 선택 사항)

• channels.bluebubbles.enrichGroupParticipantsFromContacts = true는 조회를 활성화합니다. 기본값: false.
• 조회는 그룹 접근, 명령 권한 부여, 멘션 게이팅이 모두 메시지 통과를 허용한 후에만 실행됩니다.
• 이름이 없는 전화 참가자만 보강됩니다.
• 로컬 일치 항목을 찾지 못하면 원시 전화번호가 대체값으로 유지됩니다.

{
  channels: {
    bluebubbles: {
      enrichGroupParticipantsFromContacts: true,
    },
  },
}

​

멘션 게이팅(그룹)

• 멘션 감지에는 agents.list[].groupChat.mentionPatterns(또는 messages.groupChat.mentionPatterns)를 사용합니다.
• 그룹에 대해 requireMention이 활성화되면, 에이전트는 멘션되었을 때만 응답합니다.
• 권한 있는 발신자의 제어 명령은 멘션 게이팅을 우회합니다.

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // 모든 그룹의 기본값
        "iMessage;-;chat123": { requireMention: false }, // 특정 그룹에 대한 재정의
      },
    },
  },
}

​

명령 게이팅

• 제어 명령(예: /config, /model)에는 권한 부여가 필요합니다.
• 명령 권한 부여를 결정하는 데 allowFrom과 groupAllowFrom을 사용합니다.
• 권한 있는 발신자는 그룹에서 멘션 없이도 제어 명령을 실행할 수 있습니다.

​

ACP 대화 바인딩

• DM 또는 허용된 그룹 채팅 안에서 /acp spawn codex --bind here를 실행합니다.
• 이후 같은 BlueBubbles 대화의 메시지는 생성된 ACP 세션으로 라우팅됩니다.
• /new와 /reset은 같은 바인딩된 ACP 세션을 그 자리에서 재설정합니다.
• /acp close는 ACP 세션을 닫고 바인딩을 제거합니다.

• +15555550123 또는 user@example.com 같은 정규화된 DM 핸들
• chat_id:<id>
• chat_guid:<guid>
• chat_identifier:<identifier>

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "bluebubbles",
        accountId: "default",
        peer: { kind: "dm", id: "+15555550123" },
      },
      acp: { label: "codex-imessage" },
    },
  ],
}

​

타이핑 + 읽음 확인

• 타이핑 표시기: 응답 생성 전과 생성 중에 자동으로 전송됩니다.
• 읽음 확인: channels.bluebubbles.sendReadReceipts로 제어됩니다(기본값: true).
• 타이핑 표시기: OpenClaw는 타이핑 시작 이벤트를 전송하며, BlueBubbles는 전송 또는 타임아웃 시 자동으로 타이핑을 해제합니다(DELETE를 통한 수동 중지는 신뢰할 수 없음).

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // 읽음 확인 비활성화
    },
  },
}

​

고급 작업

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // 탭백 (기본값: true)
        edit: true, // 보낸 메시지 편집 (macOS 13+, macOS 26 Tahoe에서는 깨짐)
        unsend: true, // 메시지 전송 취소 (macOS 13+)
        reply: true, // 메시지 GUID 기준 답장 스레딩
        sendWithEffect: true, // 메시지 효과 (slam, loud 등)
        renameGroup: true, // 그룹 채팅 이름 변경
        setGroupIcon: true, // 그룹 채팅 아이콘/사진 설정 (macOS 26 Tahoe에서 불안정)
        addParticipant: true, // 그룹에 참가자 추가
        removeParticipant: true, // 그룹에서 참가자 제거
        leaveGroup: true, // 그룹 채팅 나가기
        sendAttachment: true, // 첨부파일/미디어 전송
      },
    },
  },
}

• react: 탭백 반응 추가/제거 (messageId, emoji, remove)
• edit: 보낸 메시지 편집 (messageId, text)
• unsend: 메시지 전송 취소 (messageId)
• reply: 특정 메시지에 답장 (messageId, text, to)
• sendWithEffect: iMessage 효과와 함께 전송 (text, to, effectId)
• renameGroup: 그룹 채팅 이름 변경 (chatGuid, displayName)
• setGroupIcon: 그룹 채팅의 아이콘/사진 설정 (chatGuid, media) — macOS 26 Tahoe에서 불안정(API가 성공을 반환해도 아이콘이 동기화되지 않을 수 있음).
• addParticipant: 그룹에 사용자 추가 (chatGuid, address)
• removeParticipant: 그룹에서 사용자 제거 (chatGuid, address)
• leaveGroup: 그룹 채팅 나가기 (chatGuid)
• upload-file: 미디어/파일 전송 (to, buffer, filename, asVoice)
  • 음성 메모: MP3 또는 CAF 오디오와 함께 asVoice: true를 설정하면 iMessage 음성 메시지로 전송됩니다. BlueBubbles는 음성 메모 전송 시 MP3 → CAF로 변환합니다.
• 레거시 별칭: sendAttachment도 계속 작동하지만, 정식 작업 이름은 upload-file입니다.

​

메시지 ID(짧은 형식 vs 전체 형식)

• MessageSid / ReplyToId는 짧은 ID일 수 있습니다.
• MessageSidFull / ReplyToIdFull에는 provider의 전체 ID가 들어 있습니다.
• 짧은 ID는 메모리 내 값이며, 재시작 또는 캐시 제거 시 만료될 수 있습니다.
• 작업은 짧은 messageId와 전체 messageId를 모두 허용하지만, 더 이상 사용할 수 없는 짧은 ID는 오류가 발생합니다.

• 템플릿: {{MessageSidFull}}, {{ReplyToIdFull}}
• 컨텍스트: 수신 페이로드의 MessageSidFull / ReplyToIdFull

​

블록 스트리밍

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // 블록 스트리밍 활성화(기본적으로 꺼짐)
    },
  },
}

​

미디어 + 제한

• 수신 첨부파일은 다운로드되어 미디어 캐시에 저장됩니다.
• 수신 및 발신 미디어의 용량 제한은 channels.bluebubbles.mediaMaxMb로 제어합니다(기본값: 8 MB).
• 발신 텍스트는 channels.bluebubbles.textChunkLimit까지 청크로 분할됩니다(기본값: 4000자).

​

구성 참조

• channels.bluebubbles.enabled: 채널 활성화/비활성화.
• channels.bluebubbles.serverUrl: BlueBubbles REST API 기본 URL.
• channels.bluebubbles.password: API 비밀번호.
• channels.bluebubbles.webhookPath: 웹훅 엔드포인트 경로(기본값: /bluebubbles-webhook).
• channels.bluebubbles.dmPolicy: pairing | allowlist | open | disabled (기본값: pairing).
• channels.bluebubbles.allowFrom: DM 허용 목록(핸들, 이메일, E.164 번호, chat_id:*, chat_guid:*).
• channels.bluebubbles.groupPolicy: open | allowlist | disabled (기본값: allowlist).
• channels.bluebubbles.groupAllowFrom: 그룹 발신자 허용 목록.
• channels.bluebubbles.enrichGroupParticipantsFromContacts: macOS에서 게이팅 통과 후 이름 없는 그룹 참가자를 로컬 연락처로부터 선택적으로 보강합니다. 기본값: false.
• channels.bluebubbles.groups: 그룹별 구성(requireMention 등).
• channels.bluebubbles.sendReadReceipts: 읽음 확인 전송(기본값: true).
• channels.bluebubbles.blockStreaming: 블록 스트리밍 활성화(기본값: false; 스트리밍 답장에 필요).
• channels.bluebubbles.textChunkLimit: 발신 청크 크기(문자 수, 기본값: 4000).
• channels.bluebubbles.chunkMode: length(기본값)는 textChunkLimit를 초과할 때만 분할합니다. newline은 길이 기준 분할 전에 빈 줄(문단 경계)에서 분할합니다.
• channels.bluebubbles.mediaMaxMb: 수신/발신 미디어 용량 제한(MB, 기본값: 8).
• channels.bluebubbles.mediaLocalRoots: 발신 로컬 미디어 경로에 허용되는 절대 로컬 디렉터리의 명시적 허용 목록. 이를 구성하지 않으면 로컬 경로 전송은 기본적으로 거부됩니다. 계정별 재정의: channels.bluebubbles.accounts.<accountId>.mediaLocalRoots.
• channels.bluebubbles.historyLimit: 컨텍스트용 최대 그룹 메시지 수(0이면 비활성화).
• channels.bluebubbles.dmHistoryLimit: DM 기록 제한.
• channels.bluebubbles.actions: 특정 작업 활성화/비활성화.
• channels.bluebubbles.accounts: 다중 계정 구성.

• agents.list[].groupChat.mentionPatterns(또는 messages.groupChat.mentionPatterns).
• messages.responsePrefix.

​

주소 지정 / 전달 대상

• chat_guid:iMessage;-;+15555550123 (그룹에 권장)
• chat_id:123
• chat_identifier:...
• 직접 핸들: +15555550123, user@example.com
  • 직접 핸들에 기존 DM 채팅이 없으면 OpenClaw가 POST /api/v1/chat/new를 통해 새로 생성합니다. 이 기능을 사용하려면 BlueBubbles Private API가 활성화되어 있어야 합니다.

​

보안

• 웹훅 요청은 guid/password 쿼리 매개변수 또는 헤더를 channels.bluebubbles.password와 비교하여 인증됩니다.
• API 비밀번호와 웹훅 엔드포인트는 비밀로 유지하세요(자격 증명처럼 취급하세요).
• BlueBubbles 웹훅 인증에는 localhost 우회가 없습니다. 웹훅 트래픽을 프록시하는 경우 요청 전 구간에 걸쳐 BlueBubbles 비밀번호를 유지하세요. 여기서 gateway.trustedProxies는 channels.bluebubbles.password를 대체하지 않습니다. 게이트웨이 보안을 참조하세요.
• LAN 외부에 노출하는 경우 BlueBubbles 서버에서 HTTPS + 방화벽 규칙을 활성화하세요.

​

문제 해결

• 타이핑/읽음 이벤트가 더 이상 작동하지 않으면 BlueBubbles 웹훅 로그를 확인하고 게이트웨이 경로가 channels.bluebubbles.webhookPath와 일치하는지 검증하세요.
• 페어링 코드는 1시간 후 만료됩니다. openclaw pairing list bluebubbles 및 openclaw pairing approve bluebubbles <code>를 사용하세요.
• 반응 기능에는 BlueBubbles private API(POST /api/v1/message/react)가 필요합니다. 서버 버전이 이를 노출하는지 확인하세요.
• 편집/전송 취소는 macOS 13+ 및 호환되는 BlueBubbles 서버 버전이 필요합니다. macOS 26(Tahoe)에서는 private API 변경으로 인해 현재 편집 기능이 깨져 있습니다.
• 그룹 아이콘 업데이트는 macOS 26(Tahoe)에서 불안정할 수 있습니다. API는 성공을 반환해도 새 아이콘이 동기화되지 않을 수 있습니다.
• OpenClaw는 BlueBubbles 서버의 macOS 버전을 기준으로 알려진 문제 있는 작업을 자동으로 숨깁니다. macOS 26(Tahoe)에서 여전히 편집이 표시되면 channels.bluebubbles.actions.edit=false로 수동 비활성화하세요.
• 상태/헬스 정보는 openclaw status --all 또는 openclaw status --deep를 사용하세요.

​

관련 문서

• 채널 개요 — 지원되는 모든 채널
• 페어링 — DM 인증 및 페어링 흐름
• 그룹 — 그룹 채팅 동작 및 멘션 게이팅
• 채널 라우팅 — 메시지용 세션 라우팅
• 보안 — 접근 모델 및 보안 강화