iMessage

상태: 네이티브 외부 CLI 통합입니다. Gateway는 imsg rpc을 생성하고 stdio를 통해 JSON-RPC로 통신하므로 별도의 데몬이나 포트가 없습니다. 완전한 iMessage 채널을 사용하려면 비공개 API 모드를 적극 권장합니다. 답장, 탭백, 효과, 투표, 첨부 파일 답장 및 그룹 작업에는 imsg launch과 성공적인 비공개 API 프로브가 필요합니다.

일반적인 로컬 설정에서는 OpenClaw 설정이 로그인된 Messages Mac에서 imsg을 Homebrew로 설치하거나 업데이트하도록 사용자 확인 후 제안할 수 있습니다. 수동 설정 및 SSH 래퍼 토폴로지는 계속 운영자가 관리합니다. Gateway 또는 래퍼를 실행할 동일한 사용자 컨텍스트에서 imsg을 설치하거나 업데이트하십시오.

빠른 설정

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // SCP 첨부 파일 가져오기에 사용  includeAttachments: true,  // 선택 사항: 추가로 허용할 첨부 파일 루트(기본값  // /Users/*/Library/Messages/Attachments와 병합됨).  attachmentRoots: ["/Users/*/Library/Messages/Attachments"],  remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],},},}

요구 사항 및 권한(macOS)

• imsg을 실행하는 Mac의 Messages에 로그인되어 있어야 합니다.
• OpenClaw/imsg을 실행하는 프로세스 컨텍스트에는 전체 디스크 접근 권한이 필요합니다(Messages DB 접근).
• Messages.app을 통해 메시지를 전송하려면 자동화 권한이 필요합니다.
• 고급 작업(반응 / 편집 / 전송 취소 / 스레드 답장 / 효과 / 투표 / 그룹 작업)을 사용하려면 시스템 무결성 보호를 비활성화해야 합니다. imsg 비공개 API 활성화를 참조하십시오. 기본 텍스트 및 미디어 송수신은 비활성화하지 않아도 작동합니다.

Messages에 Apple 이벤트를 보낼 권한이 없습니다. (-1743)

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

imsg 비공개 API 활성화

imsg은 두 가지 운영 모드로 제공됩니다. OpenClaw에서는 사용자가 기대하는 네이티브 iMessage 작업을 채널에 제공하므로 비공개 API 모드를 권장합니다. 기본 모드는 위험이 낮은 설치, 초기 확인 또는 SIP를 비활성화할 수 없는 호스트에 여전히 유용합니다.

• 기본 모드(기본값, SIP 변경 불필요): send을 통한 아웃바운드 텍스트 및 미디어, 인바운드 감시/기록, 채팅 목록을 제공합니다. 새 brew install steipete/tap/imsg과 위의 표준 macOS 권한만으로 즉시 사용할 수 있는 모드입니다.
• 비공개 API 모드: imsg은 내부 IMCore 함수를 호출하기 위해 Messages.app에 헬퍼 dylib를 주입합니다. 이를 통해 react, edit, unsend, reply(스레드 방식), sendWithEffect, poll 및 poll-vote(네이티브 Messages 투표), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup과 입력 표시기 및 읽음 확인 기능이 활성화됩니다.

이 페이지에서 권장하는 작업 기능에는 비공개 API 모드가 필요합니다. imsg README에는 이 요구 사항이 명시되어 있습니다.

read, typing, launch, 브리지 기반 리치 전송, 메시지 변경 및 채팅 관리와 같은 고급 기능은 선택 사항입니다. 이러한 기능을 사용하려면 SIP를 비활성화하고 헬퍼 dylib를 Messages.app에 주입해야 합니다. SIP가 활성화된 경우 imsg launch은 주입을 거부합니다.

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

설정

1. Messages.app을 실행하는 Mac에 imsg을 설치(또는 업그레이드)하십시오.

   brew install steipete/tap/imsgbrew update && brew upgrade imsgimsg --versionimsg status --json

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

2. 시스템 무결성 보호(System Integrity Protection)와 (최신 macOS에서는) 라이브러리 검증을 비활성화하십시오. Apple이 서명한 Messages.app에 Apple 이외의 헬퍼 dylib을 주입하려면 SIP를 끄고 라이브러리 검증도 완화해야 합니다. 복구 모드에서 수행하는 SIP 단계는 macOS 버전에 따라 다릅니다.

   • macOS 10.13-10.15(Sierra-Catalina): Terminal에서 Library Validation을 비활성화하고 복구 모드로 재부팅한 다음 csrutil disable을 실행하고 재시작하십시오.
   • macOS 11+(Big Sur 이상), Intel: 복구 모드(또는 인터넷 복구)에서 csrutil disable을 실행하고 재시작하십시오.
   • macOS 11+, Apple Silicon: 전원 버튼 시동 절차를 통해 복구 모드로 진입하십시오. 최신 macOS 버전에서는 Continue를 클릭할 때 Left Shift 키를 누른 상태로 유지한 다음 csrutil disable을 실행하십시오. 가상 머신 환경에서는 별도의 절차를 따르므로 먼저 VM 스냅샷을 생성하십시오.

   macOS 11 이상에서는 csrutil disable만으로는 대개 충분하지 않습니다. Apple은 플랫폼 바이너리인 Messages.app에 대해 여전히 라이브러리 검증을 적용하므로, SIP가 꺼져 있어도 임시 서명된 헬퍼가 거부됩니다(Library Validation failed: ... platform binary, but mapped file is not). SIP를 비활성화한 후 라이브러리 검증도 비활성화하고 재부팅하십시오.

   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까지 헬퍼를 주입하기에 충분합니다. 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가 로드 시 임시 서명된 헬퍼를 거부하므로 브리지가 준비되지 않고 실행 시간이 초과됩니다. 이 시간 초과는 Tahoe에서 대부분의 사용자가 겪는 증상입니다. 해결 방법은 위의 plist이며, 더 과격한 조치가 아닙니다.

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

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 워크로드에는 SIP가 비활성화된 별도의 비 Apple Silicon Mac(또는 전용 봇 Mac)을 사용할 수 있습니다. 아래의 전용 봇 macOS 사용자(별도의 iMessage ID)를 참조하십시오.

액세스 제어 및 라우팅

{  channels: {    imessage: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15555550123"],      groups: {        "*": { systemPrompt: "영국식 철자를 사용하십시오." },        "8421": {          requireMention: true,          systemPrompt: "여기는 온콜 교대 채팅입니다. 답변은 3문장 이내로 작성하십시오.",        },        "9907": {          // 명시적 억제: 와일드카드 "영국식 철자를 사용하십시오."는 여기에 적용되지 않습니다.          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을(를) 사용하십시오.

{  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이 도착하기 전에 흔히 "URL을 보내 주세요"라고 응답함), 2번째 턴에서 URL을 받습니다. 이는 Apple의 전송 파이프라인에서 발생하며 OpenClaw나 imsg에서 유발하는 동작이 아닙니다.

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이 한꺼번에 내보낼 수 있는 오래된 "백로그 폭탄"을 억제합니다. 기본 동작은 항상 활성화되어 있으며 인바운드 중복 제거를 기반으로 합니다.

• 재생 중복 제거. 디스패치된 모든 인바운드 메시지는 Apple GUID를 기준으로 영구 Plugin 상태(imessage.inbound-dedupe)에 기록되며, 수집 시점에 점유되고 처리 후 커밋됩니다(일시적 실패 시 다시 시도할 수 있도록 해제됨). 이미 처리된 항목은 두 번 디스패치되지 않고 삭제됩니다. 이를 통해 메시지별 기록 없이도 복구 재생을 적극적으로 수행할 수 있습니다.
• 중단 시간 복구. 시작 시 모니터는 마지막으로 디스패치된 chat.db rowid(계정별로 유지되는 커서)를 기억하여 since_rowid으로 imsg watch.subscribe에 전달합니다. 따라서 imsg는 Gateway가 중단된 동안 도착한 행을 재생한 다음 실시간으로 추적합니다. 재생은 가장 최근 500개 행과 최대 약 2시간 전의 메시지로 제한되며, 중복 제거 기능은 이미 처리된 항목을 삭제합니다.
• 오래된 백로그 시간 제한. 시작 경계보다 위에 있는 행은 실제 실시간 행입니다. 전송 날짜가 도착 시점보다 약 15분 이상 오래된 행은 Push 플러시 백로그로 간주되어 억제됩니다. 재생된 행(경계 이하)은 대신 더 넓은 복구 시간 범위를 사용하므로 최근에 누락된 메시지는 전달하고 오래된 기록은 전달하지 않습니다.

복구는 로컬과 원격 cliPath 설정 모두에서 작동합니다. since_rowid 재생이 동일한 imsg RPC 연결을 통해 실행되기 때문입니다. 차이는 시간 범위입니다. Gateway가 chat.db을 읽을 수 있는 경우(로컬), 시작 rowid 경계를 기준으로 삼고 재생 범위를 제한하며 최대 약 2시간 전에 누락된 메시지를 전달합니다. 원격 SSH cliPath에서는 데이터베이스를 읽을 수 없으므로 재생에 제한이 없고 모든 행에 실시간 시간 제한이 적용됩니다. 따라서 최근에 누락된 메시지는 계속 복구하고 오래된 백로그도 계속 억제하지만 실시간 시간 범위가 더 좁습니다. 더 넓은 복구 시간 범위를 사용하려면 Messages가 실행되는 Mac에서 Gateway를 실행하십시오.

운영자에게 표시되는 신호

억제된 백로그는 기본 로그 수준으로 기록되며 자동으로 삭제되지 않습니다(recovery 플래그는 적용된 시간 범위를 표시함).

imessage: 오래된 인바운드 백로그 억제됨 account=<id> sent=<iso> recovery=<bool> (시작 이후 &lt;N&gt;개 억제됨)

마이그레이션

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 인증 및 페어링 흐름
• 그룹 — 그룹 채팅 동작 및 멘션 게이팅
• 채널 라우팅 — 메시지의 세션 라우팅
• 보안 — 접근 모델 및 보안 강화