BlueBubbles에서 전환하기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

이 마이그레이션이 적합한 경우

• Messages.app에 로그인된 동일한 Mac(또는 SSH로 접근 가능한 Mac)에서 이미 imsg를 실행 중입니다.
• 별도의 BlueBubbles 서버, 인증할 REST 엔드포인트, Webhook 배관 없이 이동 부품을 하나 줄이고 싶습니다. 서버 + 클라이언트 앱 + 헬퍼 대신 단일 CLI 바이너리만 사용합니다.
• 비공개 API 프로브가 available: true를 보고하는 지원되는 macOS / imsg 빌드를 사용 중입니다.

​

imsg가 하는 일

• 읽기는 읽기 전용 SQLite 핸들을 사용하여 ~/Library/Messages/chat.db에서 가져옵니다.
• 실시간 수신 메시지는 imsg watch / watch.subscribe에서 가져오며, 이는 폴링 폴백과 함께 chat.db 파일 시스템 이벤트를 추적합니다.
• 전송은 일반 텍스트 및 파일 전송에 Messages.app 자동화를 사용합니다.
• 고급 동작은 imsg launch를 사용해 imsg 헬퍼를 Messages.app에 주입합니다. 이것이 읽음 확인, 입력 표시기, 리치 전송, 편집, 전송 취소, 스레드 답장, 탭백, 그룹 관리를 가능하게 합니다.
• Linux 빌드는 복사된 chat.db를 검사할 수 있지만 전송하거나, 실시간 Mac 데이터베이스를 감시하거나, Messages.app을 구동할 수는 없습니다. OpenClaw iMessage의 경우 로그인된 Mac에서 또는 해당 Mac으로의 SSH 래퍼를 통해 imsg를 실행하세요.

​

시작하기 전에

1. Messages.app을 실행하는 Mac에 imsg를 설치합니다.
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   imsg chats가 unable to open database file, 빈 출력 또는 authorization denied로 실패하면 imsg를 실행하는 터미널, 편집기, Node 프로세스, Gateway 서비스 또는 SSH 부모 프로세스에 전체 디스크 접근 권한을 부여한 뒤 해당 부모 프로세스를 다시 여세요.
2. OpenClaw 구성을 변경하기 전에 읽기, 감시, 전송, RPC 표면을 확인합니다.
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   42를 imsg chats의 실제 채팅 ID로 바꾸세요. 전송에는 Messages.app에 대한 자동화 권한이 필요합니다. OpenClaw가 SSH를 통해 실행될 예정이라면 OpenClaw가 사용할 동일한 SSH 래퍼 또는 사용자 컨텍스트에서 이 명령을 실행하세요.
3. 고급 동작이 필요할 때 비공개 API 브리지를 활성화합니다.
   imsg launch
   imsg status --json
   
   imsg launch에는 SIP가 비활성화되어 있어야 합니다. 기본 전송, 기록, 감시는 imsg launch 없이도 작동하지만 고급 동작은 작동하지 않습니다.
4. OpenClaw를 통해 브리지를 확인합니다.
   openclaw channels status --probe
   
   imessage.privateApi.available: true가 필요합니다. false를 보고하면 먼저 이를 수정하세요. 기능 감지를 참조하세요.
5. 구성을 스냅샷합니다.
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

구성 변환

​

그룹 레지스트리 함정

1. 보낸 사람 / 채팅 대상 허용 목록(channels.imessage.groupAllowFrom) — isAllowedIMessageSender가 확인합니다. 수신 메시지를 보낸 사람 핸들, chat_guid, chat_identifier, 또는 chat_id로 매칭합니다. BlueBubbles와 같은 형태입니다.
2. 그룹 레지스트리(channels.imessage.groups) — inbound-processing.ts:199의 resolveChannelGroupPolicy가 확인합니다. groupPolicy: "allowlist"에서는 이 게이트에 다음 중 하나가 필요합니다.
   • groups: { "*": { ... } } 와일드카드 항목(allowAll = true 설정), 또는
   • groups 아래의 명시적인 chat_id별 항목.

• groupPolicy: "allowlist"가 설정되어 있지만 channels.imessage.groups가 비어 있을 때("*" 와일드카드 없음, chat_id별 항목 없음), 메시지가 도착하기 전에 계정별로 한 번 발생하는 시작 시 warn.
• 특정 그룹이 런타임에 처음 삭제될 때 chat_id별로 한 번 발생하는 warn. chat_id와 이를 허용하기 위해 groups에 추가할 정확한 키를 명시합니다.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

단계별 안내

1. 기존 BlueBubbles 블록 옆에 iMessage 블록을 추가합니다. 새 경로가 검증될 때까지만 이전 블록을 복사 원본으로 유지하세요.
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. 드라이런 프로브 — Gateway를 시작하고 iMessage가 정상 상태로 보고되는지 확인합니다.
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   imessage.enabled가 아직 false이므로 인바운드 iMessage 트래픽은 아직 라우팅되지 않습니다. 하지만 --probe가 브리지를 실행하므로 전환 전에 권한/설치 문제를 잡을 수 있습니다.
3. 전환합니다. 한 번의 구성 편집으로 BlueBubbles 구성을 제거하고 iMessage를 활성화합니다.
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Gateway를 다시 시작합니다. 이제 인바운드 iMessage 트래픽이 번들된 Plugin을 통해 흐릅니다.
4. DM을 검증합니다. 에이전트에게 다이렉트 메시지를 보내고 응답이 도착하는지 확인합니다.
5. 그룹을 별도로 검증합니다. DM과 그룹은 서로 다른 코드 경로를 사용합니다. DM 성공이 그룹 라우팅을 증명하지는 않습니다. 페어링된 그룹 채팅에서 에이전트에게 메시지를 보내고 응답이 도착하는지 확인합니다. 그룹이 조용해지면(에이전트 응답 없음, 오류 없음) Gateway 로그에서 imessage: dropping group message from chat_id=<id> 또는 시작 시 imessage: groupPolicy="allowlist" but channels.imessage.groups is empty 줄을 확인하세요. 둘 다 기본 로그 수준에서 발생합니다. 둘 중 하나가 표시되면 groups 블록이 없거나 비어 있는 것입니다. 위의 “그룹 레지스트리 함정”을 참고하세요.
6. 작업 표면을 검증합니다 — 페어링된 DM에서 에이전트에게 반응, 편집, 보내기 취소, 답장, 사진 전송을 요청하고, 그룹에서는 그룹 이름 변경 / 참가자 추가 또는 제거를 요청합니다. 각 작업은 Messages.app에 네이티브로 반영되어야 합니다. 어떤 작업이든 “iMessage <action> requires the imsg private API bridge”를 던지면 imsg launch를 다시 실행하고 channels status --probe를 새로 고칩니다.
7. iMessage DM, 그룹, 작업이 검증되면 BlueBubbles 서버와 구성을 제거합니다. OpenClaw는 channels.bluebubbles를 사용하지 않습니다.

​

작업 호환성 한눈에 보기

​

페어링, 세션 및 ACP 바인딩

• 페어링 승인은 핸들 기준으로 이어집니다. 알려진 발신자를 다시 승인할 필요가 없습니다. channels.imessage.allowFrom은 BlueBubbles가 사용하던 동일한 +15555550123 / user@example.com 문자열을 인식합니다.
• 세션은 에이전트 + 채팅별로 범위가 유지됩니다. DM은 기본 session.dmScope=main 아래에서 에이전트 메인 세션으로 접히고, 그룹 세션은 chat_id별로 격리됩니다. 세션 키는 다릅니다(agent:<id>:imessage:group:<chat_id>와 BlueBubbles의 동등한 키). BlueBubbles 세션 키 아래의 이전 대화 기록은 iMessage 세션으로 이어지지 않습니다.
• match.channel: "bluebubbles"를 참조하는 ACP 바인딩은 "imessage"로 업데이트해야 합니다. match.peer.id 형태(chat_id:, chat_guid:, chat_identifier:, 원시 핸들)는 동일합니다.

​

롤백 채널 없음

​

관련 항목

• iMessage — imsg launch 설정 및 기능 감지를 포함한 전체 iMessage 채널 참조.
• /channels/bluebubbles — 이 마이그레이션 가이드로 리디렉션되는 레거시 URL.
• 페어링 — DM 인증 및 페어링 흐름.
• 채널 라우팅 — Gateway가 아웃바운드 응답용 채널을 선택하는 방식.