iMessage

​

Thiết lập nhanh

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

​

Yêu cầu và quyền (macOS)

• Messages phải được đăng nhập trên Mac chạy imsg.
• Cần Full Disk Access cho ngữ cảnh tiến trình chạy OpenClaw/imsg (truy cập DB Messages).
• Cần quyền Automation để gửi tin nhắn qua Messages.app.
• Đối với hành động nâng cao (react / edit / unsend / threaded reply / effects / polls / group ops), System Integrity Protection phải bị tắt — xem Bật API riêng tư của imsg bên dưới. Gửi/nhận văn bản và phương tiện cơ bản hoạt động mà không cần điều này.

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

​

Bật API riêng tư của imsg

• Chế độ cơ bản (mặc định, không cần thay đổi SIP): văn bản và phương tiện đầu ra qua send, theo dõi/lịch sử đầu vào, danh sách cuộc trò chuyện. Đây là những gì bạn có ngay sau khi brew install steipete/tap/imsg mới cùng các quyền macOS chuẩn ở trên.
• Chế độ API riêng tư: imsg tiêm một helper dylib vào Messages.app để gọi các hàm IMCore nội bộ. Điều này mở khóa react, edit, unsend, reply (theo luồng), sendWithEffect, poll và poll-vote (khảo sát Messages gốc), renameGroup, setGroupIcon, addParticipant, removeParticipant, leaveGroup, cùng chỉ báo đang nhập và biên nhận đã đọc.

Các tính năng nâng cao như read, typing, launch, gửi phong phú dựa trên bridge, sửa đổi tin nhắn và quản lý cuộc trò chuyện là tùy chọn bật. Chúng yêu cầu tắt SIP và tiêm một helper dylib vào Messages.app. imsg launch từ chối tiêm khi SIP đang bật.

​

Thiết lập

1. Cài đặt (hoặc nâng cấp) imsg trên Mac chạy Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg status --json
   
   Đầu ra imsg status --json báo cáo bridge_version, rpc_methods và selectors theo từng phương thức để bạn có thể thấy bản build hiện tại hỗ trợ gì trước khi bắt đầu.
2. Tắt System Integrity Protection, và (trên macOS hiện đại) Library Validation. Việc tiêm một helper dylib không phải của Apple vào Messages.app đã ký bởi Apple cần SIP tắt và library validation được nới lỏng. Bước SIP trong Recovery-mode phụ thuộc vào phiên bản macOS:
   • macOS 10.13-10.15 (Sierra-Catalina): tắt Library Validation qua Terminal, khởi động lại vào Recovery Mode, chạy csrutil disable, khởi động lại.
   • macOS 11+ (Big Sur trở lên), Intel: Recovery Mode (hoặc Internet Recovery), csrutil disable, khởi động lại.
   • macOS 11+, Apple Silicon: trình tự khởi động bằng nút nguồn để vào Recovery; trên các phiên bản macOS gần đây, giữ phím Left Shift khi bạn nhấp Continue, rồi csrutil disable. Thiết lập máy ảo theo một luồng riêng, nên hãy tạo snapshot VM trước.
   Trên macOS 11 trở lên, chỉ csrutil disable thường là chưa đủ. Apple vẫn áp dụng library validation đối với Messages.app như một platform binary, nên helper ký adhoc bị từ chối (Library Validation failed: ... platform binary, but mapped file is not) ngay cả khi SIP đã tắt. Sau khi tắt SIP, cũng tắt library validation và khởi động lại:
   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
   
   macOS 26 (Tahoe), đã xác minh trên 26.5.1: SIP tắt cộng với lệnh DisableLibraryValidation ở trên là đủ để tiêm helper trên các phiên bản 26.0 đến 26.5.x. Không cần boot-args. Plist là yếu tố quyết định và là bước thiếu phổ biến nhất khi tiêm thất bại trên Tahoe:
   • Có plist: imsg launch tiêm được và imsg status báo cáo advanced_features: true.
   • Không có plist (ngay cả khi SIP tắt): imsg launch thất bại với Failed to launch: Timeout waiting for Messages.app to initialize. AMFI từ chối helper adhoc khi tải, nên bridge không bao giờ sẵn sàng và quá trình launch hết thời gian chờ. Timeout đó là triệu chứng mà hầu hết mọi người gặp trên Tahoe, và cách sửa là plist ở trên, không phải biện pháp nào mạnh tay hơn.
   Điều này đã được xác nhận bằng kiểm thử trước/sau có kiểm soát trên macOS 26.5.1 (Apple Silicon): có plist thì dylib được map vào Messages.app và bridge khởi động; xóa plist rồi khởi động lại thì imsg launch tạo ra lỗi timeout ở trên, với dylib không được map. Nếu việc tiêm qua imsg launch hoặc các selectors cụ thể bắt đầu trả về false sau khi nâng cấp macOS, cổng kiểm tra này thường là nguyên nhân. Hãy kiểm tra trạng thái SIP và xác thực thư viện trước khi cho rằng chính bước SIP đã thất bại. Nếu các thiết lập đó đúng mà bridge vẫn không thể tiêm, hãy thu thập imsg status --json cùng đầu ra của imsg launch và báo cáo cho dự án imsg thay vì nới lỏng thêm các kiểm soát bảo mật trên toàn hệ thống. Làm theo quy trình Recovery mode của Apple cho máy Mac của bạn để tắt SIP trước khi chạy imsg launch.
3. Tiêm helper. Khi SIP đã tắt và Messages.app đã đăng nhập:
   imsg launch
   
   imsg launch từ chối tiêm khi SIP vẫn đang bật, nên lệnh này cũng đóng vai trò xác nhận rằng bước 2 đã có hiệu lực.
4. Xác minh bridge từ OpenClaw:
   openclaw channels status --probe
   
   Mục iMessage nên báo cáo works, và imsg status --json | jq '{rpc_methods, selectors}' nên hiển thị các năng lực mà bản dựng macOS của bạn phơi bày. Tạo cuộc thăm dò ý kiến yêu cầu selectors.pollPayloadMessage; bỏ phiếu yêu cầu cả selectors.pollVoteMessage và phương thức RPC poll.vote. Plugin OpenClaw chỉ quảng bá các hành động được probe đã lưu trong bộ nhớ đệm hỗ trợ, trong khi bộ nhớ đệm trống vẫn giữ trạng thái lạc quan và probe ở lần gửi đầu tiên.

​

Khi bạn không thể tắt SIP

• imsg quay về chế độ cơ bản — chỉ văn bản + media + nhận.
• Plugin OpenClaw vẫn quảng bá gửi văn bản/media và giám sát đầu vào; nó chỉ ẩn react, edit, unsend, reply, sendWithEffect, và các thao tác nhóm khỏi bề mặt hành động (theo cổng năng lực từng phương thức).
• Bạn có thể chạy một máy Mac không dùng Apple Silicon riêng (hoặc một máy Mac bot chuyên dụng) với SIP tắt cho khối lượng công việc iMessage, trong khi vẫn bật SIP trên các thiết bị chính của bạn. Xem Người dùng macOS bot chuyên dụng (danh tính iMessage riêng) bên dưới.

​

Kiểm soát truy cập và định tuyến

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

​

Liên kết hội thoại ACP

• Chạy /acp spawn codex --bind here bên trong DM hoặc chat nhóm được cho phép.
• Các tin nhắn tương lai trong cùng hội thoại iMessage đó định tuyến tới phiên ACP đã spawn.
• /new và /reset đặt lại cùng phiên ACP đã liên kết tại chỗ.
• /acp close đóng phiên ACP và xóa liên kết.

• handle DM đã chuẩn hóa như +15555550123 hoặc user@example.com
• chat_id:<id> (khuyến nghị cho liên kết nhóm ổn định)
• 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" },
    },
  ],
}

​

Mẫu triển khai

{
  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 "$@"

​

Media, chia nhỏ, và mục tiêu gửi

imsg chats --limit 20

​

Hành động API riêng tư

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

​

Ghi cấu hình

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

​

Gộp DM gửi tách (lệnh + URL trong một lần soạn)

1. Một tin nhắn văn bản ("Dump").
2. Một bong bóng xem trước URL ("https://...") với ảnh xem trước OG dưới dạng tệp đính kèm.

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

{
  messages: {
    inbound: {
      byChannel: {
        // 7000 ms covers observed Messages.app URL-preview delays.
        imessage: 7000,
      },
    },
  },
}

​

Kịch bản và những gì tác tử thấy

​

Khôi phục inbound sau khi bridge hoặc gateway khởi động lại

• Loại trùng phát lại. Mọi tin nhắn inbound đã gửi đi được ghi lại bằng Apple GUID của nó trong trạng thái Plugin bền vững (imessage.inbound-dedupe), được claim khi nạp vào và commit sau khi xử lý (được thả khi có lỗi tạm thời để có thể thử lại). Bất cứ thứ gì đã xử lý sẽ bị bỏ thay vì gửi đi hai lần. Đây là cơ chế cho phép khôi phục phát lại mạnh tay mà không cần ghi sổ từng tin nhắn.
• Khôi phục thời gian ngừng hoạt động. Khi khởi động, bộ giám sát nhớ chat.db rowid cuối cùng đã gửi đi (con trỏ theo từng tài khoản được lưu bền vững) và truyền nó cho imsg watch.subscribe dưới dạng since_rowid, để imsg phát lại các hàng đã đến khi gateway ngừng hoạt động, rồi theo dõi trực tiếp. Phát lại được giới hạn ở các hàng gần nhất và các tin nhắn tối đa khoảng 2 giờ tuổi, và cơ chế loại trùng sẽ bỏ mọi thứ đã xử lý.
• Hàng rào tuổi backlog cũ. Các hàng phía trên ranh giới khởi động thực sự là trực tiếp; hàng nào có ngày gửi cũ hơn thời điểm đến hơn khoảng 15 phút là backlog Push-flush và sẽ bị chặn. Các hàng được phát lại (ở hoặc dưới ranh giới) dùng cửa sổ khôi phục rộng hơn, nên tin nhắn mới bị lỡ gần đây vẫn được gửi trong khi lịch sử quá cũ thì không.

​

Tín hiệu hiển thị cho người vận hành

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

​

Di chuyển

​

Khắc phục sự cố

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"

​

Con trỏ tham chiếu cấu hình

• Tham chiếu cấu hình - iMessage
• Cấu hình Gateway
• Ghép đôi

​

Liên quan

• Tổng quan kênh — tất cả các kênh được hỗ trợ
• Gỡ bỏ BlueBubbles và đường dẫn imsg iMessage — thông báo và tóm tắt di chuyển
• Chuyển từ BlueBubbles — bảng chuyển đổi cấu hình và từng bước chuyển đổi
• Ghép đôi — xác thực DM và luồng ghép đôi
• Nhóm — hành vi trò chuyện nhóm và cổng nhắc đến
• Định tuyến kênh — định tuyến phiên cho tin nhắn
• Bảo mật — mô hình truy cập và tăng cường bảo mật