iMessage

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

일반적인 로컬 설정에서는 OpenClaw 설정 과정에서 로그인된 메시지 Mac에 Homebrew를 사용하여 imsg를 설치하거나 업데이트할지 사용자에게 확인 후 제안할 수 있습니다. 수동 설정 및 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에서 메시지에 로그인되어 있어야 합니다.
• OpenClaw/imsg를 실행하는 프로세스 컨텍스트에는 전체 디스크 접근 권한이 필요합니다(메시지 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를 통한 아웃바운드 텍스트 및 미디어, 인바운드 감시/기록, 채팅 목록입니다. 위의 표준 macOS 권한을 설정하고 새로 brew install steipete/tap/imsg를 실행하면 바로 사용할 수 있는 기능입니다.
• 비공개 API 모드: imsg가 내부 IMCore 함수를 호출하기 위해 Messages.app에 헬퍼 dylib를 삽입합니다. 이를 통해 react, edit, unsend, reply(스레드형), sendWithEffect, poll 및 poll-vote(네이티브 메시지 투표), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup뿐 아니라 입력 표시기와 읽음 확인도 사용할 수 있습니다.

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

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

헬퍼 삽입 기법은 imsg 자체의 dylib를 사용하여 메시지 비공개 API에 접근합니다. 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. 시스템 무결성 보호와 최신 macOS에서는 라이브러리 검증을 비활성화하십시오. Apple이 서명한 Messages.app에 Apple 이외의 헬퍼 dylib를 삽입하려면 SIP를 끄고 동시에 라이브러리 검증을 완화해야 합니다. 복구 모드에서 수행하는 SIP 단계는 macOS 버전에 따라 다릅니다.

   • macOS 10.13-10.15 (Sierra-Catalina): 터미널을 통해 라이브러리 검증을 비활성화하고 복구 모드로 재부팅한 다음 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가 꺼져 있어도 adhoc 서명된 헬퍼가 거부됩니다(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가 로드 시 adhoc 헬퍼를 거부하므로 브리지가 준비 상태가 되지 못하고 실행 시간이 초과됩니다. 이 시간 초과는 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> 작업에는 imsg 비공개 API 브리지가 필요합니다" 오류를 발생시키면 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이 턴 2에 도착하기 전에 흔히 "URL을 보내 주세요"라고 답함) URL은 턴 2에서 받습니다. 이는 Apple의 전송 파이프라인 동작이며 OpenClaw나 imsg가 만드는 것이 아닙니다.

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

{  channels: {    imessage: {      coalesceSameSenderDms: true, // 활성화 선택(기본값: false)    },  },}

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

시나리오 및 에이전트에 표시되는 내용

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

브리지 또는 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가 한꺼번에 내보낸 백로그로 간주되어 억제됩니다. 재생된 행(경계 이하)은 대신 더 넓은 복구 시간 범위를 사용하므로 최근 누락된 메시지는 전달되고 오래된 기록은 전달되지 않습니다.

since_rowid 재생은 동일한 imsg RPC 연결을 통해 실행되므로 복구는 로컬 및 원격 cliPath 설정 모두에서 작동합니다. 차이점은 시간 범위입니다. Gateway가 chat.db를 읽을 수 있는 로컬 환경에서는 시작 rowid 경계를 기준으로 삼아 재생 범위를 제한하고 최대 약 두 시간 전에 누락된 메시지를 전달합니다. 원격 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 인증 및 페어링 흐름
• 그룹 — 그룹 채팅 동작 및 멘션 게이팅
• 채널 라우팅 — 메시지 세션 라우팅
• 보안 — 접근 모델 및 보안 강화