BlueBubbles에서 iMessage로 이전

기준일: 2026-07-26
난이도: 중급
공식 기준: BlueBubbles removal and the imsg iMessage path, Coming from BlueBubbles, iMessage

OpenClaw는 BlueBubbles 채널을 더 이상 탑재하지 않습니다. BlueBubbles 지원 종료 이후 신규 iMessage 설정과 기존 사용자 모두 channels.imessage와 macOS imsg 경로로 이전해야 합니다. 현재 OpenClaw에서 남은 channels.bluebubbles 블록은 런타임이 읽지 않으며 무효입니다. 지원되는 다른 마이그레이션 경로는 없습니다.

핵심 개념

항목	현재 기준
BlueBubbles	OpenClaw에서 제거된 레거시 경로 (HTTP 서버·webhook·REST password 없음)
iMessage plugin	번들 `imessage` 플러그인 — 공식 iMessage 채널
`imsg`	Messages DB·Messages.app과 JSON-RPC(stdio)로 통신하는 CLI
SSH wrapper	Gateway가 Linux/Windows에 있을 때 signed-in Mac의 `imsg`를 원격 실행
pairing	DM 접근 승인. pairing store는 채널별이라 이전되지 않음

Gateway가 imsg를 자식 프로세스로 띄우고 stdin/stdout으로 JSON-RPC를 주고받습니다. 별도 서버·포트·webhook 인증이 없습니다.

선택 기준

새 iMessage 연동은 BlueBubbles가 아니라 channels.imessage로 시작합니다.
기존 channels.bluebubbles가 있으면 먼저 백업한 뒤 변환표·컷오버 체크리스트를 따릅니다. 즉시 삭제하지 말고 검증 후에 제거합니다.
Linux/Windows Gateway에서 iMessage가 필요하면 cliPath를 SSH wrapper로 두고, 첨부 원격 가져오기가 필요하면 remoteHost를 설정합니다.
첨부·group allowlist·private API action(react/edit/unsend 등)은 각각 검증한 뒤 켭니다.
private API 고급 동작은 imsg launch가 필요하며 SIP 비활성화 등 위험이 있습니다. 기본 송수신만이면 SIP 변경 없이 시작할 수 있습니다.

설정 키 변환표

동작 관련 키는 대부분 의미가 같고, 전송 계층(REST 서버 vs 로컬 CLI)과 그룹 레지스트리 키 형식이 바뀝니다.

BlueBubbles	bundled iMessage	비고
`channels.bluebubbles.enabled`	`channels.imessage.enabled`	동일 의미
`serverUrl`	(제거)	REST 서버 없음
`password`	(제거)	webhook 인증 없음
(없음)	`cliPath`	`imsg` 경로 또는 SSH wrapper
(없음)	`dbPath`	선택. 생략 시 auto-detect
(없음)	`remoteHost`	SSH wrapper + SCP 첨부용
`dmPolicy` / `allowFrom`	동일 키	handle 형식 유지 (`+1…`, email)
`groupPolicy` / `groupAllowFrom`	동일 키	기본 groupPolicy는 allowlist
`groups`	`groups`	`""`는 그대로 복사. 개별 항목은 numeric `chat_id`로 재키*
`includeAttachments`	동일	기본 off. BB에서 쓰였다면 명시적으로 true
`attachmentRoots` / `mediaMaxMb` / `textChunkLimit`	동일 계열	mediaMaxMb 기본은 iMessage 16MB
`actions.*`	`actions.*`	polls 등 추가 토글 가능. private API 필요
`coalesceSameSenderDms`	(제거)	imsg 0.13.1+ 가 upstream에서 처리
`match.channel: "bluebubbles"` (ACP)	`"imessage"`	바인딩 채널명 변경 필수

멀티 계정 accounts.* 도 일대일 대응합니다.

그룹 레지스트리 주의

iMessage는 그룹 메시지에 두 게이트를 연속 적용합니다.

발신자/채팅 allowlist (groupAllowFrom, 미설정 시 allowFrom)
그룹 레지스트리 (groups) — 키는 숫자 chat_id

BlueBubbles는 GUID/identifier 키를 쓰는 경우가 많아, 항목을 그대로 복사하면 레지스트리가 “채워진 상태”인데 키가 맞지 않아 모든 그룹 메시지가 드롭될 수 있습니다. "*" 와일드카드는 그대로 두고, 특정 그룹만 허용할 때는 imsg chats로 chat_id를 확인한 뒤 재키합니다. DM 성공이 그룹 라우팅 성공을 보장하지 않습니다.

실습

1. Messages Mac에서 imsg 검증

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg --version
imsg chats --limit 3
imsg rpc --help

Full Disk Access·Automation 권한을 imsg와 Gateway(또는 SSH 부모) 프로세스 컨텍스트에 부여합니다.

2. 읽기·전송·RPC 스모크

imsg chats --limit 10 --json
imsg history --chat-id 42 --limit 5 --json
imsg send --chat-id 42 --text "OpenClaw imsg test"

3. (선택) private API bridge

imsg launch
imsg status --json

4. 설정 예시 (컷오버 전 disabled)

{
  channels: {
    imessage: {
      enabled: false,
      cliPath: "/opt/homebrew/bin/imsg",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
      includeAttachments: true,
    },
  },
}

enabled: true 후 Gateway 재시작:

openclaw gateway restart
openclaw channels status --probe --channel imessage
openclaw pairing list imessage

5. 검증 순서

DM 한 통
허용 그룹 한 통 (별도 확인)
첨부 (켠 경우)
사용하는 private API action (react/edit/unsend/reply 등)
통과 후 channels.bluebubbles 블록과 BlueBubbles 서버 제거

이전되지 않는 것

pairing-store 승인 → iMessage에서 재 pairing 또는 allowFrom에 handle 추가
BlueBubbles session 키 아래 대화 이력 → iMessage session으로 자동 이관 없음
serverUrl / password / webhook URL → 대응 키 없음

롤백용 BlueBubbles 런타임은 없습니다. 검증 실패 시 channels.imessage.enabled: false 로 두고 imsg 문제를 고친 뒤 재시도합니다.

도구에 입력할 프롬프트

BlueBubbles에서 OpenClaw iMessage로 이전하는 컷오버 계획을 만들어줘.
사전 백업, imsg 권한, config 변환표 적용, groups chat_id 재키,
gateway 재시작, DM/group/attachment/private API 검증,
이전 서버 제거 시점을 단계별로 나눠줘.

체크리스트

channels.bluebubbles를 “그대로 복사”해 새 설치에 넣지 않는다.
serverUrl/password를 iMessage 설정에 옮기지 않았다.
Messages Mac에서 Full Disk Access와 Automation 권한을 확인했다.
imsg chats와 openclaw channels status --probe --channel imessage가 통과한다.
groups 개별 키를 numeric chat_id로 맞췄거나 "*"를 사용한다.
DM, group, attachment, private API action을 따로 테스트한다.
ACP match.channel을 imessage로 바꿨다.
BlueBubbles 세션 키와 iMessage 세션 키가 다르다는 점을 이해했다.
검증 후에만 BlueBubbles 서버와 레거시 설정 블록을 제거한다.

다음 단계

iMessage 채널 설정에서 신규 설정·원격 Gateway 패턴을 진행합니다.
접근 제어와 라우팅에서 pairing과 allowlist를 설계합니다.
변경 이력에서 2026.5.18 이후 관련 릴리즈 노트를 확인합니다.

BlueBubbles에서 iMessage로 이전

기준일: 2026-07-26
난이도: 중급
공식 기준: BlueBubbles removal and the imsg iMessage path, Coming from BlueBubbles, iMessage

핵심 개념

항목	현재 기준
BlueBubbles	OpenClaw에서 제거된 레거시 경로 (HTTP 서버·webhook·REST password 없음)
iMessage plugin	번들 `imessage` 플러그인 — 공식 iMessage 채널
`imsg`	Messages DB·Messages.app과 JSON-RPC(stdio)로 통신하는 CLI
SSH wrapper	Gateway가 Linux/Windows에 있을 때 signed-in Mac의 `imsg`를 원격 실행
pairing	DM 접근 승인. pairing store는 채널별이라 이전되지 않음

Gateway가 imsg를 자식 프로세스로 띄우고 stdin/stdout으로 JSON-RPC를 주고받습니다. 별도 서버·포트·webhook 인증이 없습니다.

선택 기준

새 iMessage 연동은 BlueBubbles가 아니라 channels.imessage로 시작합니다.
기존 channels.bluebubbles가 있으면 먼저 백업한 뒤 변환표·컷오버 체크리스트를 따릅니다. 즉시 삭제하지 말고 검증 후에 제거합니다.
Linux/Windows Gateway에서 iMessage가 필요하면 cliPath를 SSH wrapper로 두고, 첨부 원격 가져오기가 필요하면 remoteHost를 설정합니다.
첨부·group allowlist·private API action(react/edit/unsend 등)은 각각 검증한 뒤 켭니다.
private API 고급 동작은 imsg launch가 필요하며 SIP 비활성화 등 위험이 있습니다. 기본 송수신만이면 SIP 변경 없이 시작할 수 있습니다.

설정 키 변환표

동작 관련 키는 대부분 의미가 같고, 전송 계층(REST 서버 vs 로컬 CLI)과 그룹 레지스트리 키 형식이 바뀝니다.

BlueBubbles	bundled iMessage	비고
`channels.bluebubbles.enabled`	`channels.imessage.enabled`	동일 의미
`serverUrl`	(제거)	REST 서버 없음
`password`	(제거)	webhook 인증 없음
(없음)	`cliPath`	`imsg` 경로 또는 SSH wrapper
(없음)	`dbPath`	선택. 생략 시 auto-detect
(없음)	`remoteHost`	SSH wrapper + SCP 첨부용
`dmPolicy` / `allowFrom`	동일 키	handle 형식 유지 (`+1…`, email)
`groupPolicy` / `groupAllowFrom`	동일 키	기본 groupPolicy는 allowlist
`groups`	`groups`	`""`는 그대로 복사. 개별 항목은 numeric `chat_id`로 재키*
`includeAttachments`	동일	기본 off. BB에서 쓰였다면 명시적으로 true
`attachmentRoots` / `mediaMaxMb` / `textChunkLimit`	동일 계열	mediaMaxMb 기본은 iMessage 16MB
`actions.*`	`actions.*`	polls 등 추가 토글 가능. private API 필요
`coalesceSameSenderDms`	(제거)	imsg 0.13.1+ 가 upstream에서 처리
`match.channel: "bluebubbles"` (ACP)	`"imessage"`	바인딩 채널명 변경 필수

멀티 계정 accounts.* 도 일대일 대응합니다.

그룹 레지스트리 주의

iMessage는 그룹 메시지에 두 게이트를 연속 적용합니다.

발신자/채팅 allowlist (groupAllowFrom, 미설정 시 allowFrom)
그룹 레지스트리 (groups) — 키는 숫자 chat_id

실습

1. Messages Mac에서 imsg 검증

brew install steipete/tap/imsg
brew update && brew upgrade imsg
imsg --version
imsg chats --limit 3
imsg rpc --help

Full Disk Access·Automation 권한을 imsg와 Gateway(또는 SSH 부모) 프로세스 컨텍스트에 부여합니다.

2. 읽기·전송·RPC 스모크

imsg chats --limit 10 --json
imsg history --chat-id 42 --limit 5 --json
imsg send --chat-id 42 --text "OpenClaw imsg test"

3. (선택) private API bridge

imsg launch
imsg status --json

4. 설정 예시 (컷오버 전 disabled)

{
  channels: {
    imessage: {
      enabled: false,
      cliPath: "/opt/homebrew/bin/imsg",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
      includeAttachments: true,
    },
  },
}

enabled: true 후 Gateway 재시작:

openclaw gateway restart
openclaw channels status --probe --channel imessage
openclaw pairing list imessage

5. 검증 순서

DM 한 통
허용 그룹 한 통 (별도 확인)
첨부 (켠 경우)
사용하는 private API action (react/edit/unsend/reply 등)
통과 후 channels.bluebubbles 블록과 BlueBubbles 서버 제거

이전되지 않는 것

pairing-store 승인 → iMessage에서 재 pairing 또는 allowFrom에 handle 추가
BlueBubbles session 키 아래 대화 이력 → iMessage session으로 자동 이관 없음
serverUrl / password / webhook URL → 대응 키 없음

롤백용 BlueBubbles 런타임은 없습니다. 검증 실패 시 channels.imessage.enabled: false 로 두고 imsg 문제를 고친 뒤 재시도합니다.

도구에 입력할 프롬프트

BlueBubbles에서 OpenClaw iMessage로 이전하는 컷오버 계획을 만들어줘.
사전 백업, imsg 권한, config 변환표 적용, groups chat_id 재키,
gateway 재시작, DM/group/attachment/private API 검증,
이전 서버 제거 시점을 단계별로 나눠줘.

체크리스트

channels.bluebubbles를 “그대로 복사”해 새 설치에 넣지 않는다.
serverUrl/password를 iMessage 설정에 옮기지 않았다.
Messages Mac에서 Full Disk Access와 Automation 권한을 확인했다.
imsg chats와 openclaw channels status --probe --channel imessage가 통과한다.
groups 개별 키를 numeric chat_id로 맞췄거나 "*"를 사용한다.
DM, group, attachment, private API action을 따로 테스트한다.
ACP match.channel을 imessage로 바꿨다.
BlueBubbles 세션 키와 iMessage 세션 키가 다르다는 점을 이해했다.
검증 후에만 BlueBubbles 서버와 레거시 설정 블록을 제거한다.

다음 단계

iMessage 채널 설정에서 신규 설정·원격 Gateway 패턴을 진행합니다.
접근 제어와 라우팅에서 pairing과 allowlist를 설계합니다.
변경 이력에서 2026.5.18 이후 관련 릴리즈 노트를 확인합니다.

BlueBubbles에서 iMessage로 이전

핵심 개념

선택 기준

설정 키 변환표

그룹 레지스트리 주의

실습

1. Messages Mac에서 imsg 검증

2. 읽기·전송·RPC 스모크

3. (선택) private API bridge

4. 설정 예시 (컷오버 전 disabled)

5. 검증 순서

이전되지 않는 것

도구에 입력할 프롬프트

체크리스트

다음 단계

관련 가이드

BlueBubbles에서 iMessage로 이전

핵심 개념

선택 기준

설정 키 변환표

그룹 레지스트리 주의

실습

1. Messages Mac에서 imsg 검증

2. 읽기·전송·RPC 스모크

3. (선택) private API bridge

4. 설정 예시 (컷오버 전 disabled)

5. 검증 순서

이전되지 않는 것

도구에 입력할 프롬프트

체크리스트

다음 단계

관련 가이드