iMessage

​

빠른 설정

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

#!/usr/bin/env bash
exec 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 활성화를 참조하세요. 기본 텍스트 및 미디어 송수신은 이것 없이도 동작합니다.

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

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

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

​

imsg 비공개 API 활성화

• 기본 모드(기본값, 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, 입력 표시기와 읽음 확인을 해제합니다.

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

​

설정

1. Messages.app을 실행하는 Mac에 **imsg를 설치(또는 업그레이드)**하세요.
   brew install steipete/tap/imsg
   imsg --version
   imsg 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은 캐시된 프로브가 지원하는 동작만 알리며, 빈 캐시는 낙관적으로 유지되고 첫 디스패치 시 프로브합니다.

​

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: { "*": { "requireMention": true } },
    },
  },
}

{
  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 대화 바인딩

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

• +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" },
    },
  ],
}

​

배포 패턴

{
  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 bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

​

미디어, 청킹, 전송 대상

imsg chats --limit 20

​

비공개 API 작업

{
  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,
    },
  },
}

​

설정 쓰기

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

​

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

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

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

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

​

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

​

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

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

​

운영자에게 보이는 신호

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

​

마이그레이션

​

문제 해결

imsg rpc --help
imsg status --json
openclaw channels status --probe

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

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

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

openclaw channels status --probe --channel imessage

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

​

구성 참조 포인터

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

​

관련 항목

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