iMessage

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

빠른 설정

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를 실행하는 프로세스 컨텍스트에는 전체 디스크 접근 권한이 필요합니다(Messages DB 접근).
• Messages.app을 통해 메시지를 보내려면 자동화 권한이 필요합니다.
• 고급 작업(react / edit / unsend / threaded reply / effects / group ops)의 경우 System Integrity Protection을 비활성화해야 합니다 — 아래 imsg private API 활성화를 참조하세요. 기본 텍스트 및 미디어 송수신은 이 설정 없이도 작동합니다.

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

​

imsg private API 활성화

• 기본 모드(기본값, SIP 변경 필요 없음): send를 통한 아웃바운드 텍스트 및 미디어, 인바운드 감시/히스토리, 채팅 목록. 새 brew install steipete/tap/imsg와 위의 표준 macOS 권한만으로 바로 사용할 수 있는 모드입니다.
• Private API 모드: imsg가 helper dylib를 Messages.app에 주입하여 내부 IMCore 함수를 호출합니다. 이 모드에서 react, edit, unsend, reply(threaded), sendWithEffect, renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup과 입력 표시 및 읽음 확인이 활성화됩니다.

read, typing, launch, 브리지 기반 리치 전송, 메시지 변경, 채팅 관리와 같은 고급 기능은 옵트인입니다. 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을 비활성화합니다. 이는 기본 Apple 요구 사항이 OS와 하드웨어에 따라 달라지므로 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를 클릭할 때 Left Shift 키를 누른 다음 csrutil disable을 실행합니다. 가상 머신 설정은 별도 흐름을 따릅니다 — 먼저 VM 스냅샷을 찍으세요.
   • macOS 26 / Tahoe: library-validation 정책과 imagent private-entitlement 검사가 더 강화되었습니다. imsg가 이를 따라가려면 업데이트된 빌드가 필요할 수 있습니다. macOS 메이저 업그레이드 후 imsg launch 주입 또는 특정 selectors가 false를 반환하기 시작하면, SIP 단계가 성공했다고 가정하기 전에 imsg의 릴리스 노트를 확인하세요.
   imsg launch를 실행하기 전에 Mac에서 SIP를 비활성화하려면 Apple의 Recovery-mode 흐름을 따르세요.
3. helper를 주입합니다. SIP가 비활성화되고 Messages.app에 로그인된 상태에서:
   imsg launch
   
   SIP가 아직 활성화되어 있으면 imsg launch는 주입을 거부하므로, 이는 2단계가 적용되었는지 확인하는 역할도 합니다.
4. OpenClaw에서 브리지를 검증합니다.
   openclaw channels status --probe
   
   iMessage 항목은 works를 보고해야 하며, imsg status --json | jq '.selectors'는 retractMessagePart: true와 macOS 빌드가 노출하는 edit / typing / read selector를 표시해야 합니다. actions.ts의 OpenClaw Plugin 메서드별 게이팅은 기본 selector가 true인 작업만 광고하므로, 에이전트의 도구 목록에서 보이는 작업 표면은 이 호스트에서 브리지가 실제로 수행할 수 있는 것을 반영합니다.

​

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

• imsg는 기본 모드로 대체됩니다 — 텍스트 + 미디어 + 수신만 가능합니다.
• OpenClaw Plugin은 여전히 텍스트/미디어 전송 및 인바운드 모니터링을 광고합니다. 다만 메서드별 capability 게이트에 따라 react, edit, unsend, reply, sendWithEffect, group ops를 작업 표면에서 숨깁니다.
• 기본 기기에서는 SIP를 활성화한 상태로 유지하면서, iMessage 워크로드를 위해 별도의 non-Apple-Silicon Mac(또는 전용 bot Mac)을 SIP 비활성화 상태로 실행할 수 있습니다. 아래 전용 bot macOS 사용자(별도 iMessage identity)를 참조하세요.

​

접근 제어 및 라우팅

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

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

​

구성 쓰기

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

​

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

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

{
  channels: {
    imessage: {
      coalesceSameSenderDms: true, // opt in (default: false)
    },
  },
}

{
  messages: {
    inbound: {
      byChannel: {
        // 2500 ms works for most setups; raise to 4000 ms if your Mac is
        // slow or under memory pressure (observed gap can stretch past 2 s
        // then).
        imessage: 2500,
      },
    },
  },
}

​

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

​

Gateway 다운타임 이후 따라잡기

channels: {
  imessage: {
    catchup: {
      enabled: true,             // master switch (default: false)
      maxAgeMinutes: 120,        // skip rows older than now - 2h (default: 120, clamp 1..720)
      perRunLimit: 50,           // max rows replayed per startup (default: 50, clamp 1..500)
      firstRunLookbackMinutes: 30, // first run with no cursor: look back 30 min (default: 30)
      maxFailureRetries: 10,     // give up on a wedged guid after 10 dispatch failures (default: 10)
    },
  },
}

​

실행 방식

​

커서 및 재시도 의미 체계

{
  "lastSeenMs": 1717900800000,
  "lastSeenRowid": 482910,
  "updatedAt": 1717900801234,
  "failureRetries": { "<guid>": 1 }
}

• 커서는 각 성공적인 디스패치마다 전진하며, 행의 디스패치가 예외를 던지면 유지됩니다. 다음 시작 시 유지된 커서에서 같은 행을 다시 시도합니다.
• 같은 guid에 대해 maxFailureRetries회 연속 예외가 발생하면 따라잡기는 warn을 기록하고 커서를 해당 막힌 메시지 뒤로 강제로 전진시켜 이후 시작에서 진행할 수 있게 합니다.
• 이미 포기한 guid는 이후 실행에서 보이는 즉시 건너뜁니다(디스패치 시도 없음). 실행 요약의 skippedGivenUp에 집계됩니다.

​

운영자에게 보이는 신호

imessage catchup: replayed=N skippedFromMe=… skippedGivenUp=… failed=… givenUp=… fetchedCount=…
imessage catchup: giving up on guid=<guid> after <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

비활성화해 둘 때

• Gateway가 감시자 자동 재시작과 함께 계속 실행되고 공백이 항상 몇 초 미만인 경우, 기본값인 꺼짐으로 충분합니다.
• DM 볼륨이 낮고 놓친 메시지가 에이전트 동작을 바꾸지 않는 경우, firstRunLookbackMinutes 초기 기간은 처음 활성화할 때 예상 밖의 오래된 컨텍스트를 디스패치할 수 있습니다.

​

문제 해결

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

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