Đến từ BlueBubbles

​

Danh sách kiểm tra di chuyển

1. Xác minh trực tiếp imsg trên máy Mac chạy Messages.app (imsg chats, imsg history, imsg send và imsg rpc --help).
2. Sao chép các khóa hành vi từ channels.bluebubbles sang channels.imessage: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, includeAttachments, attachmentRoots, mediaMaxMb, textChunkLimit, coalesceSameSenderDms và actions.
3. Loại bỏ các khóa truyền tải không còn tồn tại: serverUrl, password, URL Webhook và thiết lập máy chủ BlueBubbles.
4. Nếu Gateway không chạy trên máy Mac Messages, hãy đặt channels.imessage.cliPath thành một trình bao SSH và đặt remoteHost để lấy tệp đính kèm từ xa.
5. Khi Gateway đã dừng, bật channels.imessage, rồi chạy openclaw channels status --probe --channel imessage.
6. Kiểm thử một DM, một nhóm được cho phép, tệp đính kèm nếu được bật, và mọi hành động API riêng tư mà bạn kỳ vọng tác nhân sẽ dùng.
7. Xóa máy chủ BlueBubbles và cấu hình channels.bluebubbles cũ sau khi đường dẫn iMessage đã được xác minh.

​

Khi nào nên di chuyển theo cách này

• Bạn đã chạy imsg trên cùng máy Mac (hoặc một máy có thể truy cập qua SSH) nơi Messages.app đã đăng nhập.
• Bạn muốn giảm một thành phần vận hành — không có máy chủ BlueBubbles riêng, không có endpoint REST cần xác thực, không có hệ thống Webhook. Một tệp nhị phân CLI duy nhất thay vì máy chủ + ứng dụng khách + trình trợ giúp.
• Bạn đang dùng một bản dựng macOS / imsg được hỗ trợ, nơi phép dò API riêng tư báo cáo available: true.

​

imsg làm gì

• Dữ liệu đọc đến từ ~/Library/Messages/chat.db bằng một handle SQLite chỉ đọc.
• Tin nhắn đến trực tiếp đến từ imsg watch / watch.subscribe, theo dõi các sự kiện hệ thống tệp của chat.db với cơ chế polling dự phòng.
• Gửi tin nhắn sử dụng tự động hóa Messages.app cho văn bản thông thường và gửi tệp.
• Các hành động nâng cao sử dụng imsg launch để chèn trình trợ giúp imsg vào Messages.app. Đây là thứ mở khóa biên nhận đã đọc, chỉ báo đang nhập, gửi phong phú, chỉnh sửa, thu hồi, trả lời theo luồng, tapbacks và quản lý nhóm.
• Các bản dựng Linux có thể kiểm tra một bản sao chat.db, nhưng không thể gửi, theo dõi cơ sở dữ liệu Mac trực tiếp, hoặc điều khiển Messages.app. Với OpenClaw iMessage, hãy chạy imsg trên máy Mac đã đăng nhập hoặc thông qua một trình bao SSH đến máy Mac đó.

​

Trước khi bắt đầu

1. Cài đặt imsg trên máy Mac chạy Messages.app:
   brew install steipete/tap/imsg
   imsg --version
   imsg chats --limit 3
   
   Nếu imsg chats thất bại với unable to open database file, đầu ra trống, hoặc authorization denied, hãy cấp Full Disk Access cho terminal, trình soạn thảo, tiến trình Node, dịch vụ Gateway hoặc tiến trình cha SSH khởi chạy imsg, rồi mở lại tiến trình cha đó.
2. Xác minh các bề mặt đọc, theo dõi, gửi và RPC trước khi thay đổi cấu hình OpenClaw:
   imsg chats --limit 10 --json | jq -s
   imsg history --chat-id 42 --limit 10 --attachments --json | jq -s
   imsg watch --chat-id 42 --reactions --json
   imsg send --chat-id 42 --text "OpenClaw imsg test"
   imsg rpc --help
   
   Thay 42 bằng một id cuộc trò chuyện thực từ imsg chats. Việc gửi yêu cầu quyền Automation cho Messages.app. Nếu OpenClaw sẽ chạy qua SSH, hãy chạy các lệnh này qua cùng trình bao SSH hoặc ngữ cảnh người dùng mà OpenClaw sẽ dùng. Nếu đọc/dò hoạt động nhưng gửi thất bại với AppleEvents -1743, hãy kiểm tra xem Automation có rơi vào /usr/libexec/sshd-keygen-wrapper hay không; xem Gửi bằng trình bao SSH thất bại với AppleEvents -1743.
3. Bật cầu nối API riêng tư khi bạn cần các hành động nâng cao:
   imsg launch
   imsg status --json
   
   imsg launch yêu cầu tắt SIP. Gửi cơ bản, lịch sử và theo dõi hoạt động mà không cần imsg launch; các hành động nâng cao thì không.
4. Sau khi bạn thêm cấu hình channels.imessage đã bật, hãy xác minh cầu nối thông qua OpenClaw:
   openclaw channels status --probe
   
   Bạn cần imessage.privateApi.available: true. Nếu nó báo cáo false, hãy sửa việc đó trước — xem Phát hiện năng lực. channels status --probe chỉ dò các tài khoản đã cấu hình và đã bật.
5. Chụp nhanh cấu hình của bạn:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Chuyển đổi cấu hình

​

Bẫy sổ đăng ký nhóm

1. Allowlist người gửi / đích trò chuyện (channels.imessage.groupAllowFrom) — được kiểm tra bởi isAllowedIMessageSender. Khớp tin nhắn đến theo handle người gửi, chat_guid, chat_identifier, hoặc chat_id. Cùng hình dạng với BlueBubbles.
2. Sổ đăng ký nhóm (channels.imessage.groups) — được kiểm tra bởi resolveChannelGroupPolicy từ inbound-processing.ts:199. Với groupPolicy: "allowlist", cổng này yêu cầu một trong hai:
   • mục ký tự đại diện groups: { "*": { ... } } (đặt allowAll = true), hoặc
   • mục rõ ràng theo từng chat_id trong groups.

• Một warn một lần khi khởi động cho mỗi tài khoản khi groupPolicy: "allowlist" được đặt nhưng channels.imessage.groups trống (không có ký tự đại diện "*", không có mục theo từng chat_id) — kích hoạt trước khi có bất kỳ tin nhắn nào đến.
• Một warn một lần cho mỗi chat_id vào lần đầu một nhóm cụ thể bị loại bỏ lúc chạy, nêu tên chat_id và khóa chính xác cần thêm vào groups để cho phép nhóm đó.

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123", "chat_guid:any;-;..."],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
}

​

Từng bước

1. Thêm một khối iMessage bên cạnh khối BlueBubbles hiện có. Giữ nó tắt trong khi Gateway vẫn đang định tuyến lưu lượng BlueBubbles:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false,
         cliPath: "/opt/homebrew/bin/imsg",
         dmPolicy: "pairing",
         allowFrom: ["+15555550123"], // copy from bluebubbles.allowFrom
         groupPolicy: "allowlist",
         groupAllowFrom: [], // copy from bluebubbles.groupAllowFrom
         groups: { "*": { requireMention: true } }, // copy from bluebubbles.groups — silently drops groups if missing, see "Group registry footgun" above
         actions: {
           reactions: true,
           edit: true,
           unsend: true,
           reply: true,
           sendWithEffect: true,
           sendAttachment: true,
         },
       },
     },
   }
   
2. Kiểm tra trước khi lưu lượng trở nên quan trọng — dừng Gateway, tạm thời bật khối iMessage, và xác nhận iMessage báo trạng thái khỏe mạnh từ CLI:
   openclaw gateway stop
   # edit config: channels.imessage.enabled = true
   openclaw channels status --probe --channel imessage   # expect imessage.privateApi.available: true
   
   channels status --probe chỉ kiểm tra các tài khoản đã cấu hình và đang bật. Không khởi động lại Gateway với cả BlueBubbles và iMessage cùng bật trừ khi bạn cố ý muốn cả hai bộ giám sát kênh cùng chạy. Nếu bạn chưa chuyển đổi ngay, đặt channels.imessage.enabled về false trước khi khởi động lại Gateway. Dùng các lệnh imsg trực tiếp trong Trước khi bắt đầu để xác thực Mac trước khi bật lưu lượng OpenClaw.
3. Chuyển đổi. Khi tài khoản iMessage đã bật báo trạng thái khỏe mạnh, xóa cấu hình BlueBubbles và giữ iMessage bật:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Khởi động lại gateway. Lưu lượng iMessage vào giờ sẽ đi qua Plugin đi kèm.
4. Xác minh DM. Gửi cho agent một tin nhắn trực tiếp; xác nhận phản hồi được gửi đến.
5. Xác minh nhóm riêng. DM và nhóm đi qua các đường dẫn mã khác nhau — DM thành công không chứng minh rằng nhóm đang được định tuyến. Gửi cho agent một tin nhắn trong cuộc trò chuyện nhóm đã ghép đôi và xác nhận phản hồi được gửi đến. Nếu nhóm im lặng (không có phản hồi của agent, không có lỗi), kiểm tra nhật ký gateway để tìm imessage: dropping group message from chat_id=<id> hoặc dòng khởi động imessage: groupPolicy="allowlist" but channels.imessage.groups is empty — cả hai đều xuất hiện ở cấp nhật ký mặc định. Nếu một trong hai xuất hiện, khối groups của bạn bị thiếu hoặc rỗng — xem “Bẫy registry nhóm” ở trên.
6. Xác minh bề mặt hành động — từ một DM đã ghép đôi, yêu cầu agent thả phản ứng, chỉnh sửa, thu hồi, trả lời, gửi ảnh, và (trong nhóm) đổi tên nhóm / thêm hoặc xóa người tham gia. Mỗi hành động phải xuất hiện nguyên bản trong Messages.app. Nếu bất kỳ hành động nào ném lỗi “iMessage <action> requires the imsg private API bridge”, chạy lại imsg launch và làm mới channels status --probe.
7. Xóa máy chủ và cấu hình BlueBubbles sau khi đã xác minh DM, nhóm và hành động của iMessage. OpenClaw sẽ không dùng channels.bluebubbles.

​

Tổng quan tương đương hành động

​

Ghép đôi, phiên và liên kết ACP

• Phê duyệt ghép đôi được chuyển tiếp theo handle. Bạn không cần phê duyệt lại những người gửi đã biết — channels.imessage.allowFrom nhận diện cùng các chuỗi +15555550123 / user@example.com mà BlueBubbles đã dùng.
• Phiên vẫn được giới hạn theo từng agent + cuộc trò chuyện. DM được gộp vào phiên chính của agent dưới mặc định session.dmScope=main; phiên nhóm vẫn cô lập theo từng chat_id. Khóa phiên khác nhau (agent:<id>:imessage:group:<chat_id> so với tương đương của BlueBubbles) — lịch sử hội thoại cũ dưới các khóa phiên BlueBubbles không được chuyển sang phiên iMessage.
• Liên kết ACP tham chiếu match.channel: "bluebubbles" cần được cập nhật thành "imessage". Các dạng match.peer.id (chat_id:, chat_guid:, chat_identifier:, handle trần) là giống hệt nhau.

​

Không có kênh rollback

​

Liên quan

• Gỡ bỏ BlueBubbles và đường dẫn iMessage imsg — thông báo ngắn và tóm tắt cho người vận hành.
• iMessage — tài liệu tham chiếu đầy đủ cho kênh iMessage, bao gồm thiết lập imsg launch và phát hiện năng lực.
• /channels/bluebubbles — URL cũ chuyển hướng đến hướng dẫn di chuyển này.
• Ghép đôi — xác thực DM và luồng ghép đôi.
• Định tuyến kênh — cách gateway chọn kênh cho phản hồi đi.