iMessage

Trạng thái: tích hợp CLI ngoài gốc. Gateway khởi chạy imsg rpc và giao tiếp qua JSON-RPC trên stdio (không có daemon/cổng riêng). Các hành động nâng cao yêu cầu imsg launch và một phép thăm dò API riêng tư thành công.

Thiết lập nhanh

brew install steipete/tap/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>

#!/usr/bin/env bashexec 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.

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

imsg đi kèm hai chế độ vận hành:

• 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.

Để dùng bề mặt hành động nâng cao mà trang kênh này ghi lại, bạn cần chế độ API riêng tư. README của imsg nêu rõ yêu cầu:

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.

Kỹ thuật tiêm helper dùng dylib riêng của imsg để truy cập API riêng tư của Messages. Không có máy chủ bên thứ ba hoặc runtime BlueBubbles trong đường dẫn iMessage của OpenClaw.

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/imsgimsg --versionimsg 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.

Nếu openclaw channels status --probe báo cáo kênh là works nhưng các hành động cụ thể ném lỗi "iMessage <action> requires the imsg private API bridge" tại thời điểm gửi, hãy chạy lại imsg launch — helper có thể bị rơi ra (Messages.app khởi động lại, cập nhật hệ điều hành, v.v.) và trạng thái available: true đã lưu trong bộ nhớ đệm sẽ tiếp tục quảng bá hành động cho đến khi lần probe tiếp theo làm mới.

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

Nếu việc tắt SIP không phù hợp với mô hình đe dọa của bạn:

• 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: {        "*": { 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

Các chat iMessage cũ cũng có thể được liên kết với phiên ACP.

Luồng thao tác nhanh:

• 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.

Liên kết bền vững được cấu hình được hỗ trợ thông qua các mục bindings[] cấp cao nhất với type: "acp" và match.channel: "imessage".

match.peer.id có thể dùng:

• 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>

Ví dụ:

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

Xem Agent ACP để biết hành vi liên kết ACP dùng chung.

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 bashexec 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ư

Khi imsg launch đang chạy và openclaw channels status --probe báo cáo privateApi.available: true, công cụ tin nhắn có thể dùng các hành động gốc của iMessage ngoài thao tác gửi văn bản thông thường.

{  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

iMessage cho phép các thao tác ghi cấu hình do kênh khởi tạo theo mặc định (cho /config set|unset khi commands.config: true).

Tắt:

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

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

Khi người dùng nhập một lệnh và một URL cùng nhau — ví dụ Dump https://example.com/article — ứng dụng Messages của Apple tách lần gửi thành hai hàng chat.db riêng biệt:

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.

Hai hàng này tới OpenClaw cách nhau khoảng 0,8-2,0 giây trên hầu hết thiết lập. Nếu không gộp, tác nhân nhận riêng lệnh ở lượt 1, trả lời (thường là "send me the URL"), và chỉ thấy URL ở lượt 2 — lúc đó ngữ cảnh lệnh đã mất. Đây là pipeline gửi của Apple, không phải thứ OpenClaw hay imsg đưa vào.

channels.imessage.coalesceSameSenderDms chọn đưa một DM vào bộ đệm các hàng liên tiếp từ cùng người gửi. Khi imsg cung cấp dấu hiệu xem trước URL có cấu trúc balloon_bundle_id: "com.apple.messages.URLBalloonProvider" trên một trong các hàng nguồn, OpenClaw chỉ gộp lần gửi tách thực sự đó và giữ mọi hàng được đệm khác thành các lượt riêng. Trên các bản dựng imsg cũ hơn hoàn toàn không phát metadata bong bóng, OpenClaw không thể phân biệt gửi tách với các lần gửi riêng, nên nó quay về gộp cả bucket. Điều đó giữ hành vi trước khi có metadata thay vì làm thụt lùi các lần gửi tách Dump <url> thành hai lượt. Trò chuyện nhóm tiếp tục dispatch theo từng tin nhắn để cấu trúc lượt nhiều người dùng được giữ nguyên.

{  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

Cột "Bật cờ" cho biết hành vi trên bản dựng imsg phát ra balloon_bundle_id. Trên các bản dựng imsg cũ hoàn toàn không phát ra siêu dữ liệu balloon, các hàng bên dưới được đánh dấu "Hai lượt" / "N lượt" sẽ quay về hợp nhất kiểu cũ (một lượt): OpenClaw không thể phân biệt về mặt cấu trúc giữa một lần gửi tách và các lần gửi riêng biệt, nên giữ hành vi hợp nhất trước khi có siêu dữ liệu. Tách chính xác được kích hoạt khi bản dựng phát ra siêu dữ liệu balloon.

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

iMessage khôi phục các tin nhắn bị lỡ khi gateway ngừng hoạt động, đồng thời chặn "bom backlog" cũ mà Apple có thể xả sau một lần khôi phục Push. Hành vi mặc định luôn bật, được xây dựng trên cơ chế loại trùng inbound.

• 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.

Khôi phục hoạt động trên cả thiết lập cliPath cục bộ và từ xa, vì phát lại since_rowid chạy qua cùng kết nối RPC imsg. Khác biệt nằm ở cửa sổ: khi gateway có thể đọc chat.db (cục bộ), nó neo ranh giới rowid lúc khởi động, giới hạn khoảng phát lại, và gửi các tin nhắn bị lỡ tối đa vài giờ tuổi. Qua cliPath SSH từ xa, nó không thể đọc cơ sở dữ liệu, nên phát lại không bị giới hạn và mọi hàng dùng hàng rào tuổi trực tiếp — vẫn khôi phục các tin nhắn mới bị lỡ gần đây và vẫn chặn backlog cũ, chỉ với cửa sổ trực tiếp hẹp hơn. Chạy gateway trên máy Mac có Messages để có cửa sổ khôi phục rộng hơn.

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

Backlog bị chặn được ghi log ở mức mặc định, không bao giờ bị bỏ âm thầm (cờ recovery cho biết cửa sổ nào đã áp dụng):

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

Di chuyển

channels.imessage.catchup.* đã bị loại bỏ dần — khôi phục thời gian ngừng hoạt động nay tự động và không cần cấu hình cho thiết lập mới. Các cấu hình hiện có với catchup.enabled: true vẫn được tôn trọng như một hồ sơ tương thích cho cửa sổ phát lại khôi phục. Các khối catchup bị tắt (enabled: false hoặc không có enabled: true) đã bị loại bỏ; openclaw doctor --fix sẽ xóa chúng.

Khắc phục sự cố

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"

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