iMessage

Trạng thái: tích hợp CLI bên ngoài dạng native. Gateway sinh tiến trình 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 lần 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 máy Mac chạy imsg.
• Full Disk Access là bắt buộc cho ngữ cảnh tiến trình đang chạy OpenClaw/imsg (truy cập CSDL Messages).
• Quyền Automation là bắt buộc để gửi tin nhắn qua Messages.app.
• Đối với các hành động nâng cao (react / edit / unsend / threaded reply / effects / group ops), System Integrity Protection phải bị tắt — xem Bật API riêng tư 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 tắt.

Bật API riêng tư imsg

imsg có hai chế độ vận hành:

• Chế độ cơ bản (mặc định, không cần thay đổi SIP): gửi văn bản và phương tiện đi qua send, theo dõi/lịch sử đến, danh sách cuộc trò chuyện. Đây là những gì bạn có ngay từ đầu sau khi 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 tiêm một dylib trợ giúp vào Messages.app để gọi các hàm IMCore nội bộ. Đây là chế độ mở khóa react, edit, unsend, reply (theo luồng), sendWithEffect, 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 mô tả, bạn cần 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ú 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 dylib trợ giúp vào Messages.app. imsg launch từ chối tiêm khi SIP đang bật.

Kỹ thuật tiêm trợ giúp 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 OpenClaw iMessage.

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/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. Việc này phụ thuộc vào phiên bản macOS vì yêu cầu nền tảng của Apple phụ thuộc vào hệ điều hành và phần cứng:

   • 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: dùng chuỗi 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 bấm Continue, rồi csrutil disable. Các thiết lập máy ảo theo một luồng riêng — hãy chụp snapshot VM trước.
   • macOS 26 / Tahoe: các chính sách library-validation và kiểm tra private-entitlement của imagent đã siết chặt hơn nữa; imsg có thể cần một bản dựng cập nhật để theo kịp. Nếu việc tiêm bằng imsg launch hoặc các selectors cụ thể bắt đầu trả về false sau một bản nâng cấp macOS lớn, hãy kiểm tra ghi chú phát hành của imsg trước khi giả định bước SIP đã thành công.

   Làm theo luồng 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 trình trợ giúp. 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 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 '.selectors' phải hiển thị retractMessagePart: true cùng bất kỳ selector edit / typing / read nào mà bản dựng macOS của bạn cung cấp. Cơ chế gating theo từng phương thức của Plugin OpenClaw trong actions.ts chỉ quảng bá các hành động có selector nền tảng là true, nên bề mặt hành động bạn thấy trong danh sách công cụ của agent phản ánh những gì bridge thực sự có thể làm trên máy chủ này.

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" vào lúc dispatch, hãy chạy lại imsg launch — trình trợ giúp 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 được lưu trong bộ nhớ đệm sẽ tiếp tục quảng bá hành động cho đến khi lần thăm dò 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 chấp nhận được với mô hình đe dọa của bạn:

• imsg quay về chế độ cơ bản — chỉ văn bản + phương tiện + nhận.
• Plugin OpenClaw vẫn quảng bá gửi văn bản/phương tiện và giám sát tin nhắn đến; nó chỉ ẩn react, edit, unsend, reply, sendWithEffect và group ops khỏi bề mặt hành động (theo cổng năng lực theo từng phương thức).
• Bạn có thể chạy một máy Mac không phải Apple Silicon riêng (hoặc một máy Mac bot chuyên dụng) đã tắt SIP 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 mình. 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 cuộc hội thoại ACP

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

Các liên kết cố định đượ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:

• định danh DM đã chuẩn hóa như +15555550123 hoặc [email protected]
• 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 tử 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: "[email protected]",      includeAttachments: true,      dbPath: "/Users/bot/Library/Messages/chat.db",    },  },}

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

Phương tiện, chia đ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ể dùng các hành động gốc iMessage ngoài việ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,      },    },  },}

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

Ghi cấu hình

iMessage cho phép 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 bị tách khi gửi (lệnh + URL trong một lần soạn)

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

Hai hàng này đến 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 chỉ nhận lệnh ở lượt 1, trả lời (thường là "hãy gửi URL cho tôi"), và chỉ thấy URL ở lượt 2 — lúc đó ngữ cảnh lệnh đã bị mất. Đây là pipeline gửi của Apple, không phải thứ do OpenClaw hay imsg đưa vào.

channels.imessage.coalesceSameSenderDms chọn cho DM gộp các hàng liên tiếp từ cùng người gửi vào một lượt tác nhân duy nhất. Trò chuyện nhóm tiếp tục gửi theo từng tin nhắn để giữ nguyên cấu trúc lượt của nhiều người dùng.

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

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

Bắt kịp sau khi Gateway ngừng hoạt động

Khi Gateway ngoại tuyến (crash, khởi động lại, Mac ngủ, máy tắt), imsg watch tiếp tục từ trạng thái chat.db hiện tại sau khi Gateway hoạt động trở lại — theo mặc định, bất kỳ thứ gì đến trong khoảng gián đoạn sẽ không bao giờ được thấy. Catchup phát lại các tin nhắn đó trong lần khởi động tiếp theo để tác nhân không âm thầm bỏ lỡ lưu lượng vào.

Catchup bị tắt theo mặc định. Bật theo từng kênh:

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

Cách chạy

Một lượt cho mỗi lần khởi động monitorIMessageProvider, được sắp xếp theo thứ tự imsg launch sẵn sàng → watch.subscribe → performIMessageCatchup → vòng lặp gửi trực tiếp. Bản thân catchup dùng chats.list + messages.history theo từng cuộc trò chuyện trên cùng client JSON-RPC mà imsg watch dùng. Bất cứ thứ gì đến trong lượt catchup sẽ đi qua cơ chế gửi trực tiếp như bình thường; cache chống trùng lặp đầu vào hiện có hấp thụ mọi phần chồng lấn với các hàng được phát lại.

Mỗi hàng được phát lại được đưa qua đường gửi trực tiếp (evaluateIMessageInbound + dispatchInboundMessage), nên allowlist, chính sách nhóm, debouncer, cache echo, và biên nhận đã đọc hoạt động giống hệt nhau trên tin nhắn được phát lại và tin nhắn trực tiếp.

Ngữ nghĩa cursor và thử lại

Catchup giữ một cursor theo từng tài khoản tại <openclawStateDir>/imessage/catchup/<account>__<hash>.json (thư mục trạng thái OpenClaw mặc định là ~/.openclaw, có thể ghi đè bằng OPENCLAW_STATE_DIR):

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

• Cursor tiến lên sau mỗi lần gửi thành công và được giữ nguyên khi việc gửi của một hàng ném lỗi — lần khởi động tiếp theo thử lại cùng hàng đó từ cursor đã giữ.
• Sau maxFailureRetries lần ném lỗi liên tiếp với cùng guid, catchup ghi log warn và buộc cursor tiến qua tin nhắn bị kẹt để các lần khởi động tiếp theo có thể tiếp tục.
• Các guid đã bị bỏ cuộc được bỏ qua ngay khi thấy (không thử gửi) trong các lần chạy sau và được tính vào skippedGivenUp trong tóm tắt lượt chạy.

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

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

Một dòng WARN ... capped to perRunLimit nghĩa là một lần khởi động chưa xả hết toàn bộ backlog. Tăng perRunLimit (tối đa 500) nếu các khoảng gián đoạn của bạn thường xuyên vượt quá lượt mặc định 50 hàng.

Khi nào nên để tắt

• Gateway chạy liên tục với watchdog tự khởi động lại và các khoảng gián đoạn luôn < vài giây — mặc định tắt là ổn.
• Lưu lượng DM thấp và tin nhắn bị bỏ lỡ sẽ không thay đổi hành vi tác nhân — cửa sổ ban đầu firstRunLookbackMinutes có thể gửi ngữ cảnh cũ bất ngờ trong lần bật đầu tiên.

Khi bạn bật catchup, lần khởi động đầu tiên không có cursor chỉ nhìn lại firstRunLookbackMinutes (mặc định 30 phút), không phải toàn bộ cửa sổ maxAgeMinutes — điều này tránh phát lại một lịch sử dài các tin nhắn trước khi bật.

Khắc phục sự cố

imsg rpc --helpimsg status --jsonopenclaw channels status --probe

#!/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ả 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 dịch 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