iMessage (레거시: imsg)

경고: 새로운 iMessage 배포에는 BlueBubbles를 사용하세요.

imsg 연동은 레거시이며 향후 릴리스에서 제거될 수 있습니다.

상태: 레거시 외부 CLI 연동. 게이트웨이가 imsg rpc를 생성하고 stdio의 JSON-RPC를 통해 통신합니다(별도 데몬/포트 불필요).

• BlueBubbles (권장) — 신규 설정에 권장되는 iMessage 경로.
• Pairing — iMessage DM은 기본적으로 페어링 모드.
• Configuration reference — 전체 iMessage 필드 레퍼런스.

빠른 설정

로컬 Mac (빠른 경로)

  ### 1단계: imsg 설치 및 확인

brew install steipete/tap/imsg
imsg rpc --help

  ### 2단계: OpenClaw 설정

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

  ### 3단계: 게이트웨이 시작

openclaw gateway

  ### 4단계: 첫 DM 페어링 승인 (기본 dmPolicy)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

    페어링 요청은 1시간 후 만료됩니다.

SSH를 통한 원격 Mac

OpenClaw는 stdio 호환 `cliPath`만 필요하므로, 원격 Mac에 SSH로 `imsg`를 실행하는 래퍼 스크립트를 `cliPath`에 지정할 수 있습니다.

#!/usr/bin/env bash
exec ssh -T gateway-host 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"],
    },
  },
}

`remoteHost`가 설정되지 않으면 OpenClaw는 SSH 래퍼 스크립트를 파싱하여 자동 감지를 시도합니다.
`remoteHost`는 `host` 또는 `user@host` 형식이어야 합니다(공백이나 SSH 옵션 없이).
OpenClaw는 SCP에 strict host-key checking을 사용하므로 릴레이 호스트 키가 `~/.ssh/known_hosts`에 이미 있어야 합니다.
첨부 파일 경로는 허용된 루트(`attachmentRoots` / `remoteAttachmentRoots`)에 대해 검증됩니다.

요구 사항 및 권한 (macOS)

• imsg를 실행하는 Mac에서 Messages에 로그인되어 있어야 합니다.
• OpenClaw/imsg를 실행하는 프로세스 컨텍스트에 전체 디스크 접근 권한이 필요합니다(Messages DB 접근).
• Messages.app을 통해 메시지를 전송하려면 자동화 권한이 필요합니다.

팁: 권한은 프로세스 컨텍스트별로 부여됩니다. 게이트웨이가 헤드리스(LaunchAgent/SSH)로 실행되는 경우, 동일한 컨텍스트에서 일회성 대화형 명령을 실행하여 프롬프트를 트리거하세요:

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

접근 제어 및 라우팅

DM 정책

`channels.imessage.dmPolicy`가 다이렉트 메시지를 제어합니다:

- `pairing` (기본값)
- `allowlist`
- `open` (`allowFrom`에 `"*"` 필요)
- `disabled`

허용 목록 필드: `channels.imessage.allowFrom`.

허용 목록 항목은 핸들 또는 채팅 대상(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)이 될 수 있습니다.

그룹 정책 + 멘션

`channels.imessage.groupPolicy`가 그룹 처리를 제어합니다:

- `allowlist` (설정 시 기본값)
- `open`
- `disabled`

그룹 발신자 허용 목록: `channels.imessage.groupAllowFrom`.

런타임 폴백: `groupAllowFrom`이 미설정이면 iMessage 그룹 발신자 확인이 사용 가능한 `allowFrom`으로 폴백합니다.
런타임 참고: `channels.imessage`가 완전히 없으면 `channels.defaults.groupPolicy`가 설정되어 있더라도 런타임이 `groupPolicy="allowlist"`로 폴백하고 경고를 로그에 기록합니다.

그룹의 멘션 게이팅:

- iMessage에는 네이티브 멘션 메타데이터가 없음
- 멘션 감지는 정규식 패턴 사용 (`agents.list[].groupChat.mentionPatterns`, 폴백 `messages.groupChat.mentionPatterns`)
- 설정된 패턴이 없으면 멘션 게이팅을 적용할 수 없음

인가된 발신자의 제어 명령은 그룹에서 멘션 게이팅을 우회할 수 있습니다.

세션 및 결정적 응답

- DM은 직접 라우팅; 그룹은 그룹 라우팅 사용.
- 기본 `session.dmScope=main`으로 iMessage DM은 에이전트 메인 세션으로 통합됩니다.
- 그룹 세션은 격리됩니다 (`agent:<agentId>:imessage:group:<chat_id>`).
- 응답은 원본 채널/대상 메타데이터를 사용하여 iMessage로 라우팅됩니다.

그룹 유사 스레드 동작:

일부 다중 참여자 iMessage 스레드가 `is_group=false`로 도착할 수 있습니다.
해당 `chat_id`가 `channels.imessage.groups` 아래에 명시적으로 설정되어 있으면 OpenClaw가 그룹 트래픽으로 처리합니다(그룹 게이팅 + 그룹 세션 격리).

배포 패턴

전용 Apple ID와 macOS 사용자를 사용하여 봇 트래픽을 개인 Messages 프로필과 격리합니다.

일반적인 흐름:

1. 전용 macOS 사용자 생성/로그인.
2. 해당 사용자에서 봇 Apple ID로 Messages에 로그인.
3. 해당 사용자에 `imsg` 설치.
4. OpenClaw가 해당 사용자 컨텍스트에서 `imsg`를 실행할 수 있도록 SSH 래퍼 생성.
5. `channels.imessage.accounts.<id>.cliPath`와 `.dbPath`를 해당 사용자 프로필로 지정.

첫 실행 시 봇 사용자 세션에서 GUI 승인(자동화 + 전체 디스크 접근)이 필요할 수 있습니다.

일반적인 토폴로지:

- 게이트웨이는 Linux/VM에서 실행
- iMessage + `imsg`는 tailnet의 Mac에서 실행
- `cliPath` 래퍼가 SSH로 `imsg` 실행
- `remoteHost`가 SCP 첨부 파일 가져오기 활성화

예시:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.openclaw/scripts/imsg-ssh",
      remoteHost: "[email protected]",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

SSH와 SCP가 비대화형이 되도록 SSH 키를 사용하세요.
`known_hosts`가 채워지도록 먼저 호스트 키를 신뢰하세요(예: `ssh [email protected]`).

iMessage는 `channels.imessage.accounts`에서 계정별 설정을 지원합니다.

각 계정은 `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, 히스토리 설정, 첨부 파일 루트 허용 목록 등의 필드를 재정의할 수 있습니다.

미디어, 분할, 전달 대상

- 인바운드 첨부 파일 수집은 선택 사항: `channels.imessage.includeAttachments`
- `remoteHost`가 설정되면 SCP를 통해 원격 첨부 파일 경로를 가져올 수 있음
- 첨부 파일 경로는 허용된 루트와 일치해야 함:
  - `channels.imessage.attachmentRoots` (로컬)
  - `channels.imessage.remoteAttachmentRoots` (원격 SCP 모드)
  - 기본 루트 패턴: `/Users/*/Library/Messages/Attachments`
- SCP는 strict host-key checking 사용 (`StrictHostKeyChecking=yes`)
- 아웃바운드 미디어 크기는 `channels.imessage.mediaMaxMb` 사용 (기본값 16 MB)

- 텍스트 청크 제한: `channels.imessage.textChunkLimit` (기본값 4000)
- 분할 모드: `channels.imessage.chunkMode`
  - `length` (기본값)
  - `newline` (단락 우선 분할)

명시적 대상으로 권장:

- `chat_id:123` (안정적인 라우팅에 권장)
- `chat_guid:...`
- `chat_identifier:...`

핸들 대상도 지원됩니다:

- `imessage:+1555...`
- `sms:+1555...`
- `[email protected]`

imsg chats --limit 20

설정 쓰기

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

비활성화:

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

문제 해결

바이너리와 RPC 지원을 확인합니다:

imsg rpc --help
openclaw channels status --probe

프로브가 RPC 미지원을 보고하면 `imsg`를 업데이트하세요.

확인:

- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- 페어링 승인 (`openclaw pairing list imessage`)

확인:

- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- `channels.imessage.groups` 허용 목록 동작
- 멘션 패턴 설정 (`agents.list[].groupChat.mentionPatterns`)

확인:

- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- 게이트웨이 호스트에서의 SSH/SCP 키 인증
- 게이트웨이 호스트의 `~/.ssh/known_hosts`에 호스트 키 존재
- Messages를 실행하는 Mac에서의 원격 경로 읽기 가능성

동일한 사용자/세션 컨텍스트의 대화형 GUI 터미널에서 다시 실행하고 프롬프트를 승인합니다:

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

OpenClaw/`imsg`를 실행하는 프로세스 컨텍스트에 전체 디스크 접근 + 자동화가 부여되었는지 확인합니다.

설정 레퍼런스 포인터

• Configuration reference - iMessage
• Gateway configuration
• Pairing
• BlueBubbles