iMessage

Trạng thái: tích hợp CLI bên ngoài nguyên bản. Gateway khởi chạy imsg rpc và giao tiếp bằng JSON-RPC qua stdio — không có daemon hoặc cổng riêng. Chế độ API riêng tư được đặc biệt khuyến nghị để có một kênh iMessage đầy đủ; các thao tác trả lời, tapback, hiệu ứng, cuộc thăm dò ý kiến, trả lời tệp đính kèm và thao tác nhóm yêu cầu imsg launch cùng một lần thăm dò API riêng tư thành công.

Đối với thiết lập cục bộ phổ biến, trình thiết lập OpenClaw có thể đề nghị cài đặt hoặc cập nhật imsg qua Homebrew sau khi người dùng xác nhận trên máy Mac Messages đã đăng nhập. Việc thiết lập thủ công và các mô hình trình bao bọc SSH vẫn do người vận hành quản lý: hãy cài đặt hoặc cập nhật imsg trong cùng ngữ cảnh người dùng sẽ chạy Gateway hoặc trình bao bọc.

Thiết lập nhanh

brew install steipete/tap/imsgbrew update && brew upgrade 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>

ssh messages-mac 'brew install steipete/tap/imsg && brew update && brew upgrade imsg'

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

{channels: {imessage: {  enabled: true,  cliPath: "~/.openclaw/scripts/imsg-ssh",  remoteHost: "user@gateway-host", // dùng để tìm nạp tệp đính kèm qua SCP  includeAttachments: true,  // Tùy chọn: các thư mục gốc tệp đính kèm bổ sung được phép (hợp nhất với  // /Users/*/Library/Messages/Attachments mặc định).  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 máy Mac chạy imsg.
• Ngữ cảnh tiến trình chạy OpenClaw/imsg phải có quyền Truy cập toàn bộ ổ đĩa (để truy cập cơ sở dữ liệu Messages).
• Cần có quyền Tự động hóa để gửi tin nhắn thông qua Messages.app.
• Đối với các thao tác nâng cao (bày tỏ cảm xúc / chỉnh sửa / thu hồi / trả lời theo luồng / hiệu ứng / cuộc thăm dò ý kiến / thao tác nhóm), phải tắt System Integrity Protection — xem Bật API riêng tư của imsg. Việc gửi/nhận văn bản và phương tiện cơ bản vẫn hoạt động khi không tắt tính năng này.

Không được ủy quyền gửi sự kiện Apple đến Messages. (-1743)

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

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

imsg được cung cấp với hai chế độ vận hành. Đối với OpenClaw, chế độ API riêng tư là thiết lập được khuyến nghị vì nó mang đến cho kênh các thao tác iMessage nguyên bản mà người dùng mong đợi. Chế độ cơ bản vẫn hữu ích cho các bản cài đặt ít rủi ro, quá trình xác minh ban đầu hoặc các máy chủ không thể tắt SIP.

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

Bề mặt thao tác được khuyến nghị trên trang này yêu cầu chế độ API riêng tư. README của imsg nêu rõ yêu cầu này:

Các tính năng nâng cao như read, typing, launch, gửi nội dung phong phú có cầu nối hỗ trợ, thay đổi tin nhắn và quản lý cuộc trò chuyện là tùy chọn chủ động. Chúng yêu cầu tắt SIP và chèn một dylib trợ giúp vào Messages.app. imsg launch từ chối chèn khi SIP đang bật.

Kỹ thuật chèn trình trợ giúp sử dụng dylib riêng của imsg để truy cập các 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 máy Mac chạy Messages.app:

   brew install steipete/tap/imsgbrew update && brew upgrade 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ể xem bản dựng hiện tại hỗ trợ những gì trước khi bắt đầu.

2. Tắt System Integrity Protection và (trên macOS hiện đại) Library Validation. Việc chèn một dylib trợ giúp không phải của Apple vào Messages.app được Apple ký yêu cầu phải tắt SIP và nới lỏng quy trình xác thực thư viện. Bước SIP trong chế độ Khôi phục 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, rồi khởi động lại.
   • macOS 11+ (Big Sur trở lên), Intel: vào Recovery Mode (hoặc Internet Recovery), chạy csrutil disable, rồi khởi động lại.
   • macOS 11+, Apple Silicon: dùng 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 vào Continue, rồi chạy csrutil disable. Thiết lập máy ảo tuân theo một quy trình riêng, vì vậy trước tiên hãy tạo ảnh chụp nhanh VM.

   Trên macOS 11 trở lên, chỉ csrutil disable thường là chưa đủ. Apple vẫn thực thi quy trình xác thực thư viện đối với Messages.app dưới dạng tệp nhị phân nền tảng, nên trình trợ giúp được ký adhoc sẽ 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, hãy tắt cả quy trình xác thực thư viện 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: tắt SIP cộng với lệnh DisableLibraryValidation ở trên là đủ để chèn trình trợ giúp trên các phiên bản từ 26.0 đến 26.5.x. Không cần boot-args. Plist là yếu tố quyết định và là bước thường bị thiếu nhất khi quá trình chèn thất bại trên Tahoe:

   • Có plist: imsg launch chèn thành công 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 trình trợ giúp adhoc khi tải, nên bridge không bao giờ sẵn sàng và quá trình khởi chạy hết thời gian chờ. Đây là triệu chứng mà phần lớn người dùng gặp trên Tahoe; cách khắc phục là plist ở trên, không phải biện pháp nào quyết liệt hơn.

   Nếu việc chèn imsg launch hoặc một số 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 cài đặt đó chính xác nhưng bridge vẫn không thể chèn, 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ì làm suy yếu thêm các biện pháp kiểm soát bảo mật trên toàn hệ thống.

3. Chèn trình trợ giúp. Khi SIP đã tắt và Messages.app đã đăng nhập:

   imsg launch

   imsg launch từ chối chèn khi SIP vẫn được bật, vì vậy thao tác này cũng đồng thời 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 phải báo cáo works, và imsg status --json | jq '{rpc_methods, selectors}' phải hiển thị các khả năng được bản dựng macOS của bạn cung cấp. Việc tạo cuộc thăm dò 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á những hành động được probe lưu trong bộ nhớ đệm hỗ trợ, còn bộ nhớ đệm trống vẫn giả định lạc quan và thực hiện probe trong lần điều phố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ể phát sinh lỗi "iMessage <action> requires the imsg private API bridge" tại thời điểm điều phối, hãy chạy lại imsg launch — trình trợ giúp có thể bị ngắt kết nối (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 được lưu trong bộ nhớ đệm sẽ tiếp tục quảng bá các hành động cho đến khi probe tiếp theo làm mới trạng thái.

Khi SIP vẫn được bật

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

• imsg chuyển về chế độ cơ bản — chỉ văn bản + phương tiện + nhận.
• Plugin OpenClaw vẫn quảng bá chức năng gửi văn bản/phương tiện và giám sát đầu vào; Plugin ẩ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 khả năng của 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 biệt (hoặc máy Mac dành riêng cho bot) với SIP đã tắt để xử lý 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. Xem Người dùng macOS dành riêng cho bot (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 cuộc hội thoại ACP

Các cuộc trò chuyện iMessage 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 cuộc trò chuyện nhóm được phép.
• Các tin nhắn sau đó trong cùng cuộc hội thoại iMessage sẽ được định tuyến đến phiên ACP vừa tạo.
• /new và /reset đặt lại tại chỗ cùng phiên ACP đã liên kết.
• /acp close đóng phiên ACP và xóa liên kết.

Các liên kết bền vững được cấu hình sử dụng 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> (được 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 Tác nhân ACP để biết hành vi liên kết ACP dùng chung.

Mô hình 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 "$@"

Phương tiện, phân đoạn và đích 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ể sử dụng các hành động gốc của iMessage bên cạnh việc gửi văn bản thông thường.

Tất cả hành động được bật theo mặc định; sử dụng channels.imessage.actions để tắt từng hành động riêng lẻ:

{  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

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

Tắt:

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

Gộp các DM bị tách khi gửi (lệnh + URL trong cùng một lần soạn)

Khi người dùng nhập lệnh cùng với URL — 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://...") có các ảnh xem trước OG dưới dạng tệp đính kèm.

Trên hầu hết hệ thống, hai hàng đến OpenClaw cách nhau khoảng 0.8-2.0 giây. Nếu không gộp, agent nhận riêng lệnh ở lượt 1 (và thường trả lời "hãy gửi URL cho tôi") trước khi URL đến ở lượt 2. Đây là pipeline gửi của Apple, không phải do OpenClaw hay imsg tạo ra.

channels.imessage.coalesceSameSenderDms cho phép một DM tham gia cơ chế đệ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 cấu trúc của bản xem trước URL balloon_bundle_id: "com.apple.messages.URLBalloonProvider" trên một trong các hàng nguồn, OpenClaw chỉ gộp đúng lần gửi bị tách thực sự đó và giữ mọi hàng được đệm khác thành các lượt riêng biệt. Trên các bản dựng imsg cũ hoàn toàn không phát siêu dữ liệu bong bóng, OpenClaw không thể phân biệt lần gửi bị tách với các lần gửi riêng biệt, nên sẽ dự phòng bằng cách gộp nhóm. Cách này duy trì hành vi trước khi có siêu dữ liệu thay vì làm suy giảm các lần gửi bị tách Dump <url> thành hai lượt. Các cuộc trò chuyện nhóm tiếp tục gửi đi theo từng tin nhắn để duy trì cấu trúc lượt của nhiều người dùng.

{  channels: {    imessage: {      coalesceSameSenderDms: true, // chọn tham gia (mặc định: false)    },  },}

{  messages: {    inbound: {      byChannel: {        // 7000 ms bao phủ độ trễ xem trước URL quan sát được của Messages.app.        imessage: 7000,      },    },  },}

Các tình huống và nội dung agent nhìn thấy

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

Khôi phục dữ liệu đến sau khi bridge hoặc Gateway khởi động lại

iMessage khôi phục các tin nhắn bị bỏ lỡ trong khi Gateway ngừng hoạt động, đồng thời ngăn chặn "bom dữ liệu tồn đọng" cũ mà Apple có thể xả ra sau khi khôi phục Push. Hành vi mặc định luôn được bật, dựa trên cơ chế tiếp nhận bền vững và hàng rào tuổi.

• Bảo vệ bền vững khỏi phát lại. Trước khi nâng con trỏ khôi phục, OpenClaw ghi nhật ký từng hàng thô vào hàng đợi tiếp nhận SQLite dùng chung, sử dụng GUID Apple của hàng đó làm ID sự kiện. Một hàng đã hoàn tất để lại dấu vết xóa trong khoảng 4 giờ, giới hạn ở 10,000 mục, vì vậy lần phát lại có cùng GUID sẽ bị loại bỏ ngay cả sau khi khởi động lại. Một hàng đang chờ vẫn có thể được khôi phục cho đến khi quá trình gửi đi tiếp nhận hàng đó.
• Khôi phục thời gian ngừng hoạt động. Khi khởi động, trình giám sát ghi nhớ rowid của hàng chat.db được tiếp nhận bền vững gần nhất (một con trỏ bền vững cho mỗi tài khoản) và truyền nó cho imsg watch.subscribe dưới dạng since_rowid, để imsg phát lại các hàng chưa được ghi nhật ký rồi theo dõi dữ liệu trực tiếp. Các hàng được ghi nhật ký trước khi xảy ra sự cố sẽ tiếp tục từ SQLite. Việc phát lại được giới hạn ở 500 hàng gần nhất và các tin nhắn có tuổi tối đa khoảng 2 giờ; dấu vết xóa GUID sẽ loại bỏ mọi nội dung đã được xử lý.
• Hàng rào tuổi cho dữ liệu tồn đọng cũ. Các hàng phía trên ranh giới khởi động thực sự là dữ liệu trực tiếp; hàng có ngày gửi sớm hơn thời điểm đến quá khoảng 15 phút là dữ liệu tồn đọng do Push xả ra và sẽ bị ngăn chặn. Thay vào đó, các hàng được phát lại (tại hoặc bên dưới ranh giới) sử dụng cửa sổ khôi phục rộng hơn, để tin nhắn vừa bị bỏ lỡ được chuyển đến còn lịch sử quá cũ thì không.

Quá trình khôi phục hoạt động trên cả thiết lập cliPath cục bộ lẫn từ xa, vì việc phát lại since_rowid chạy qua cùng kết nối RPC imsg. Điểm khác biệt là cửa sổ: khi Gateway có thể đọc chat.db (cục bộ), nó neo ranh giới rowid khởi động, giới hạn khoảng phát lại và chuyển các tin nhắn bị bỏ lỡ có tuổi tối đa vài giờ. Qua cliPath SSH từ xa, nó không thể đọc cơ sở dữ liệu, nên việc phát lại không bị giới hạn và mọi hàng đều sử dụng hàng rào tuổi trực tiếp — cơ chế này vẫn khôi phục các tin nhắn vừa bị bỏ lỡ và vẫn ngăn dữ liệu tồn đọng cũ, chỉ với cửa sổ trực tiếp hẹp hơn. Hãy chạy Gateway trên máy Mac chạy 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

Dữ liệu tồn đọng bị ngăn chặn được ghi nhật ký ở cấp độ mặc định, không bao giờ bị loại bỏ âm thầm (cờ recovery cho biết cửa sổ nào đã được áp dụng):

imessage: đã ngăn dữ liệu đến tồn đọng cũ account=<id> sent=<iso> recovery=<bool> (&lt;N&gt; mục bị ngăn kể từ khi khởi động)

Di chuyển

channels.imessage.catchup.* đã lỗi thời — quá trình khôi phục thời gian ngừng hoạt động diễn ra tự động và không cần cấu hình cho các 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 dưới dạng hồ sơ tương thích cho cửa sổ phát lại khôi phục. Các khối bắt kịp đã tắt (enabled: false hoặc không có enabled: true) đã bị loại bỏ; openclaw doctor --fix 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"

Tham chiếu cấu hình

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

Liên quan

• Tổng quan về các kênh — tất cả các kênh được hỗ trợ
• Việc loại bỏ BlueBubbles và đường dẫn iMessage qua imsg — thông báo và tóm tắt quá trình di chuyển
• Chuyển từ BlueBubbles — bảng chuyển đổi cấu hình và quy trình chuyển đổi từng bước
• Ghép nối — luồng xác thực tin nhắn trực tiếp và ghép nối
• Nhóm — hành vi trò chuyện nhóm và cơ chế kiểm soát bằng đề cập
• Đị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