iMessage

상태: 네이티브 외부 CLI 통합. Gateway는 imsg rpc를 생성하고 stdio의 JSON-RPC를 통해 통신합니다(별도 daemon/port 없음). 고급 동작에는 imsg launch와 성공적인 비공개 API 프로브가 필요합니다.

빠른 설정

brew install steipete/tap/imsgimsg rpc --helpimsg launchopenclaw channels status --probe

{channels: {imessage: {enabled: true,cliPath: "/usr/local/bin/imsg",dbPath: "/Users/user/Library/Messages/chat.db",},},}

openclaw gateway

openclaw pairing list imessageopenclaw pairing approve imessage <CODE>

#!/usr/bin/env bashexec ssh -T gateway-host imsg "$@"

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // used for SCP attachment fetches  includeAttachments: true,  // Optional: override allowed attachment roots.  // Defaults include /Users/*/Library/Messages/Attachments  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

요구 사항 및 권한(macOS)

• imsg를 실행하는 Mac에서 Messages에 로그인되어 있어야 합니다.
• OpenClaw/imsg를 실행하는 프로세스 컨텍스트에 Full Disk Access가 필요합니다(Messages DB 접근).
• Messages.app을 통해 메시지를 보내려면 자동화 권한이 필요합니다.
• 고급 동작(반응 / 편집 / 전송 취소 / 스레드 답장 / 효과 / 투표 / 그룹 작업)에는 System Integrity Protection을 비활성화해야 합니다. 아래 imsg 비공개 API 활성화를 참조하세요. 기본 텍스트 및 미디어 송수신은 이것 없이도 동작합니다.

Not authorized to send Apple events to Messages. (-1743)

kTCCServiceAppleEvents | /usr/libexec/sshd-keygen-wrapper | auth_value=0 | com.apple.MobileSMS

imsg 비공개 API 활성화

imsg는 두 가지 운영 모드로 제공됩니다.

• 기본 모드(기본값, SIP 변경 불필요): send를 통한 아웃바운드 텍스트 및 미디어, 인바운드 watch/history, 채팅 목록. 이는 위의 표준 macOS 권한과 함께 새로 brew install steipete/tap/imsg를 실행하면 바로 얻는 기능입니다.
• 비공개 API 모드: imsg가 helper dylib를 Messages.app에 주입하여 내부 IMCore 함수를 호출합니다. 이 모드가 react, edit, unsend, reply(스레드), sendWithEffect, poll 및 poll-vote(네이티브 Messages 투표), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, 입력 표시기와 읽음 확인을 해제합니다.

이 채널 페이지에서 문서화하는 고급 동작 표면에 도달하려면 비공개 API 모드가 필요합니다. imsg README는 요구 사항을 명확히 설명합니다.

read, typing, launch, 브리지 기반 rich send, 메시지 변경, 채팅 관리 같은 고급 기능은 opt-in입니다. SIP를 비활성화하고 helper dylib를 Messages.app에 주입해야 합니다. SIP가 활성화되어 있으면 imsg launch는 주입을 거부합니다.

helper 주입 기법은 imsg 자체 dylib를 사용해 Messages 비공개 API에 접근합니다. OpenClaw iMessage 경로에는 타사 서버나 BlueBubbles runtime이 없습니다.

설정

1. Messages.app을 실행하는 Mac에 **imsg를 설치(또는 업그레이드)**하세요.

   brew install steipete/tap/imsgimsg --versionimsg status --json

   imsg status --json 출력은 bridge_version, rpc_methods, 메서드별 selectors를 보고하므로 시작하기 전에 현재 빌드가 지원하는 항목을 확인할 수 있습니다.

2. System Integrity Protection 및 (최신 macOS에서) Library Validation을 비활성화하세요. Apple 서명된 Messages.app에 비 Apple helper dylib를 주입하려면 SIP가 꺼져 있어야 하고, library validation도 완화되어야 합니다. Recovery 모드 SIP 단계는 macOS 버전별로 다릅니다.

   • macOS 10.13-10.15 (Sierra-Catalina): Terminal을 통해 Library Validation을 비활성화하고, Recovery Mode로 재부팅한 뒤 csrutil disable을 실행하고 재시작합니다.
   • macOS 11+ (Big Sur 이상), Intel: Recovery Mode(또는 Internet Recovery), csrutil disable, 재시작.
   • macOS 11+, Apple Silicon: 전원 버튼 시작 시퀀스로 Recovery에 진입합니다. 최근 macOS 버전에서는 Continue를 클릭할 때 왼쪽 Shift 키를 누른 다음 csrutil disable을 실행합니다. 가상 머신 설정은 별도 흐름을 따르므로 먼저 VM snapshot을 만드세요.

   macOS 11 이상에서는 일반적으로 csrutil disable만으로 충분하지 않습니다. Apple은 여전히 Messages.app을 platform binary로 간주해 library validation을 강제하므로, adhoc 서명된 helper는 SIP가 꺼져 있어도 거부됩니다(Library Validation failed: ... platform binary, but mapped file is not). SIP를 비활성화한 후 library validation도 비활성화하고 재부팅하세요.

   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true

   macOS 26 (Tahoe), 26.5.1에서 확인됨: SIP 비활성화 및 위의 DisableLibraryValidation 명령만으로 26.0부터 26.5.x까지 helper 주입에 충분합니다. boot-args는 필요하지 않습니다. plist가 결정적 요소이며, Tahoe에서 주입이 실패할 때 가장 흔히 빠지는 단계입니다.

   • plist가 있는 경우: imsg launch가 주입되고 imsg status가 advanced_features: true를 보고합니다.
   • plist가 없는 경우(SIP가 꺼져 있어도): imsg launch가 Failed to launch: Timeout waiting for Messages.app to initialize로 실패합니다. AMFI가 로드 시 adhoc helper를 거부하므로 브리지가 준비되지 않고 launch가 시간 초과됩니다. 이 시간 초과가 Tahoe에서 대부분의 사용자가 마주치는 증상이며, 해결책은 위의 plist이지 더 과격한 조치가 아닙니다.

   이는 macOS 26.5.1(Apple Silicon)에서 통제된 전/후 비교로 확인되었습니다. plist가 있으면 dylib가 Messages.app에 매핑되고 브리지가 올라옵니다. plist를 제거하고 재부팅하면 imsg launch가 위의 시간 초과 실패를 내며 dylib가 매핑되지 않습니다.

   If imsg launch 주입 또는 특정 selectors가 macOS 업그레이드 후 false를 반환하기 시작하면, 보통 이 게이트가 원인입니다. SIP 단계 자체가 실패했다고 가정하기 전에 SIP 및 라이브러리 검증 상태를 확인하세요. 해당 설정이 올바른데도 브리지가 여전히 주입할 수 없다면, 추가적인 시스템 전역 보안 제어를 약화하지 말고 imsg status --json과 imsg launch 출력을 수집해 imsg 프로젝트에 보고하세요.

   imsg launch를 실행하기 전에 Mac에서 SIP를 비활성화하려면 Apple의 복구 모드 흐름을 따르세요.

3. 헬퍼를 주입합니다. SIP가 비활성화되어 있고 Messages.app에 로그인된 상태에서:

   imsg launch

   SIP가 아직 활성화되어 있으면 imsg launch는 주입을 거부하므로, 이는 2단계가 적용되었는지 확인하는 역할도 합니다.

4. OpenClaw에서 브리지를 확인합니다:

   openclaw channels status --probe

   iMessage 항목은 works를 보고해야 하며, imsg status --json | jq '{rpc_methods, selectors}'는 사용 중인 macOS 빌드가 노출하는 기능을 보여야 합니다. 투표 생성에는 selectors.pollPayloadMessage가 필요합니다. 투표에는 selectors.pollVoteMessage와 poll.vote RPC 메서드가 모두 필요합니다. OpenClaw Plugin은 캐시된 프로브가 지원하는 동작만 알리며, 빈 캐시는 낙관적으로 유지되고 첫 디스패치 시 프로브합니다.

openclaw channels status --probe가 채널을 works로 보고하지만 특정 동작이 디스패치 시점에 "iMessage <action> requires the imsg private API bridge"를 던진다면, imsg launch를 다시 실행하세요. 헬퍼가 빠질 수 있으며(Messages.app 재시작, OS 업데이트 등), 캐시된 available: true 상태는 다음 프로브가 갱신될 때까지 계속 동작을 알립니다.

SIP를 비활성화할 수 없는 경우

SIP 비활성화가 위협 모델에 적합하지 않다면:

• imsg는 기본 모드로 폴백합니다. 텍스트 + 미디어 + 수신만 가능합니다.
• OpenClaw Plugin은 여전히 텍스트/미디어 전송과 인바운드 모니터링을 알립니다. 다만 메서드별 기능 게이트에 따라 react, edit, unsend, reply, sendWithEffect, 그룹 작업을 동작 표면에서 숨깁니다.
• 기본 기기에서는 SIP를 활성화한 상태로 유지하면서, iMessage 워크로드용으로 별도의 Apple Silicon이 아닌 Mac(또는 전용 봇 Mac)을 SIP 비활성화 상태로 실행할 수 있습니다. 아래의 전용 봇 macOS 사용자(별도 iMessage ID)를 참조하세요.

액세스 제어 및 라우팅

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "Use British spelling." },        "8421": {          requireMention: true,          systemPrompt: "This is the on-call rotation chat. Keep replies under 3 sentences.",        },        "9907": {          // explicit suppression: the wildcard "Use British spelling." does not apply here          systemPrompt: "",        },      },    },  },}

ACP 대화 바인딩

레거시 iMessage 채팅도 ACP 세션에 바인딩할 수 있습니다.

빠른 운영자 흐름:

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

구성된 영구 바인딩은 type: "acp" 및 match.channel: "imessage"를 포함하는 최상위 bindings[] 항목을 통해 지원됩니다.

match.peer.id는 다음을 사용할 수 있습니다:

• +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: "imessage",        accountId: "default",        peer: { kind: "group", id: "chat_id:123" },      },      acp: { label: "codex-group" },    },  ],}

공유 ACP 바인딩 동작은 ACP 에이전트를 참조하세요.

배포 패턴

{  channels: {    imessage: {      enabled: true,      cliPath: "~/.openclaw/scripts/imsg-ssh",      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

#!/usr/bin/env bashexec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

미디어, 청킹, 전송 대상

imsg chats --limit 20

비공개 API 작업

imsg launch가 실행 중이고 openclaw channels status --probe가 privateApi.available: true를 보고하면, 메시지 도구는 일반 텍스트 전송 외에도 iMessage 네이티브 작업을 사용할 수 있습니다.

{  channels: {    imessage: {      actions: {        reactions: true,        edit: true,        unsend: true,        reply: true,        sendWithEffect: true,        sendAttachment: true,        renameGroup: true,        setGroupIcon: true,        addParticipant: true,        removeParticipant: true,        leaveGroup: true,        polls: true,      },    },  },}

{  channels: {    imessage: {      sendReadReceipts: false,    },  },}

설정 쓰기

iMessage는 기본적으로 채널에서 시작한 설정 쓰기를 허용합니다(commands.config: true일 때 /config set|unset).

비활성화:

{  channels: {    imessage: {      configWrites: false,    },  },}

분할 전송 DM 병합(한 번의 작성에 명령 + URL)

사용자가 명령과 URL을 함께 입력하면(예: Dump https://example.com/article) Apple의 Messages 앱은 전송을 두 개의 별도 chat.db 행으로 분할합니다.

1. 텍스트 메시지("Dump").
2. OG 미리보기 이미지를 첨부 파일로 포함한 URL 미리보기 말풍선("https://...").

대부분의 설정에서 두 행은 약 0.8~2.0초 간격으로 OpenClaw에 도착합니다. 병합이 없으면 에이전트는 1턴에서 명령만 받고 답장하며(흔히 "URL을 보내 주세요"), 2턴에서야 URL을 보게 됩니다. 이때는 이미 명령 컨텍스트가 사라진 뒤입니다. 이는 OpenClaw나 imsg가 도입한 것이 아니라 Apple의 전송 파이프라인입니다.

channels.imessage.coalesceSameSenderDms는 DM이 같은 발신자의 연속 행을 버퍼링하도록 선택합니다. imsg가 소스 행 중 하나에 구조적 URL 미리보기 마커 balloon_bundle_id: "com.apple.messages.URLBalloonProvider"를 노출하면, OpenClaw는 실제 분할 전송만 병합하고 버퍼링된 다른 행은 별도 턴으로 유지합니다. 말풍선 메타데이터를 전혀 내보내지 않는 이전 imsg 빌드에서는 OpenClaw가 분할 전송과 개별 전송을 구분할 수 없으므로 버킷 병합으로 폴백합니다. 이는 Dump <url> 분할 전송이 두 턴으로 퇴행하지 않도록 메타데이터 이전 동작을 보존합니다. 그룹 채팅은 여러 사용자의 턴 구조가 보존되도록 계속 메시지별로 디스패치됩니다.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // 옵트인(기본값: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms는 관찰된 Messages.app URL 미리보기 지연을 포괄합니다.        imessage: 7000,      },    },  },}

시나리오와 에이전트가 보는 내용

"플래그 켜짐" 열은 balloon_bundle_id를 내보내는 imsg 빌드에서의 동작을 보여줍니다. 말풍선 메타데이터를 전혀 내보내지 않는 이전 imsg 빌드에서는 아래에서 "두 턴" / "N턴"으로 표시된 행이 대신 레거시 병합(한 턴)으로 폴백합니다. OpenClaw는 분할 전송과 별도 전송을 구조적으로 구분할 수 없으므로 메타데이터 도입 이전의 병합을 보존합니다. 빌드가 말풍선 메타데이터를 내보내면 정확한 분리가 활성화됩니다.

브리지 또는 Gateway 재시작 후 인바운드 복구

iMessage는 Gateway가 다운된 동안 놓친 메시지를 복구하면서, Push 복구 후 Apple이 플러시할 수 있는 오래된 "백로그 폭탄"을 동시에 억제합니다. 기본 동작은 항상 켜져 있으며 인바운드 중복 제거를 기반으로 합니다.

• 재생 중복 제거. 디스패치된 모든 인바운드 메시지는 영구 Plugin 상태(imessage.inbound-dedupe)에 Apple GUID로 기록되며, 수집 시점에 클레임되고 처리 후 커밋됩니다(일시적 실패 시 재시도할 수 있도록 해제). 이미 처리된 항목은 두 번 디스패치되지 않고 드롭됩니다. 이것이 복구가 메시지별 장부 없이도 적극적으로 재생할 수 있게 해줍니다.
• 다운타임 복구. 시작 시 모니터는 마지막으로 디스패치된 chat.db rowid(계정별 영구 커서)를 기억하고 이를 since_rowid로 imsg watch.subscribe에 전달합니다. 그러면 imsg가 Gateway가 다운된 동안 도착한 행을 재생한 뒤 라이브 테일링으로 전환합니다. 재생은 가장 최근 행과 약 2시간 이내 메시지로 제한되며, 중복 제거가 이미 처리된 항목을 드롭합니다.
• 오래된 백로그 나이 제한. 시작 경계보다 위의 행은 실제 라이브입니다. 전송 날짜가 도착 시점보다 약 15분 이상 오래된 행은 Push 플러시 백로그이므로 억제됩니다. 재생된 행(경계 이하)은 대신 더 넓은 복구 창을 사용하므로 최근에 놓친 메시지는 전달되고 오래된 기록은 전달되지 않습니다.

복구는 로컬 및 원격 cliPath 설정 모두에서 동작합니다. since_rowid 재생이 동일한 imsg RPC 연결을 통해 실행되기 때문입니다. 차이는 창입니다. Gateway가 chat.db를 읽을 수 있으면(로컬) 시작 rowid 경계를 고정하고, 재생 범위를 제한하며, 최대 몇 시간 전의 놓친 메시지를 전달합니다. 원격 SSH cliPath에서는 데이터베이스를 읽을 수 없으므로 재생은 제한되지 않고 모든 행이 라이브 나이 제한을 사용합니다. 즉, 최근에 놓친 메시지는 계속 복구하고 오래된 백로그도 계속 억제하지만 더 좁은 라이브 창을 사용합니다. 더 넓은 복구 창을 원하면 Messages Mac에서 Gateway를 실행하세요.

운영자에게 보이는 신호

억제된 백로그는 기본 수준에서 로깅되며 조용히 드롭되지 않습니다(recovery 플래그는 어떤 창이 적용되었는지 보여줍니다).

imessage: suppressed stale inbound backlog account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; suppressed since start)

마이그레이션

channels.imessage.catchup.*는 더 이상 권장되지 않습니다. 다운타임 복구는 이제 자동이며 새 설정에는 구성이 필요하지 않습니다. catchup.enabled: true가 있는 기존 구성은 복구 재생 창을 위한 호환성 프로필로 계속 존중됩니다. 비활성화된 catchup 블록(enabled: false 또는 enabled: true 없음)은 폐기됩니다. openclaw doctor --fix가 이를 제거합니다.

문제 해결

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

imsg chats --limit 10 --jsonimsg watch --chat-id <chat-id> --jsonsqlite3 ~/Library/Messages/chat.db \"select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

launchctl kickstart -k system/com.apple.apsdlaunchctl kickstart -k gui/$(id -u)/com.apple.CommCenterlaunchctl kickstart -k gui/$(id -u)/com.apple.identityservicesdlaunchctl kickstart -k gui/$(id -u)/com.apple.imagentimsg launchopenclaw gateway restart

#!/usr/bin/env bashexec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1imsg send <handle> "test"

구성 참조 포인터

• 구성 참조 - iMessage
• Gateway 구성
• 페어링

관련 항목

• 채널 개요 — 지원되는 모든 채널
• BlueBubbles 제거 및 imsg iMessage 경로 — 발표 및 마이그레이션 요약
• BlueBubbles에서 전환 — 구성 변환 표와 단계별 전환
• 페어링 — DM 인증 및 페어링 흐름
• 그룹 — 그룹 채팅 동작 및 멘션 게이팅
• 채널 라우팅 — 메시지의 세션 라우팅
• 보안 — 접근 모델 및 강화