Chuyển từ BlueBubbles

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Khi việc di chuyển này phù hợp

• 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 để xác thực, không có phần nối 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 bản dựng macOS / imsg được hỗ trợ, nơi phép thăm 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ế dự phòng bằng polling.
• Gửi 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 dùng imsg launch để tiêm trình trợ giúp imsg vào Messages.app. Đây là cơ chế mở khóa biên nhận đã đọc, chỉ báo đang nhập, gửi nội dung phong phú, chỉnh sửa, thu hồi, trả lời theo luồng, tapback, 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 wrapper 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 rỗng, hoặc authorization denied, hãy cấp quyền Truy cập toàn bộ ổ đĩa 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 chat id thật từ imsg chats. Việc gửi yêu cầu quyền Tự động hóa cho Messages.app. Nếu OpenClaw sẽ chạy qua SSH, hãy chạy các lệnh này thông qua cùng wrapper SSH hoặc ngữ cảnh người dùng mà OpenClaw sẽ dùng.
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. 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 điều đó trước — xem Phát hiện khả năng.
5. Chụp nhanh cấu hình của bạn:
   cp ~/.openclaw/openclaw.json5 ~/.openclaw/openclaw.json5.bak
   

​

Dịch cấu hình

​

Bẫy registry nhóm

1. Allowlist người gửi / mục tiêu 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 dạng với BlueBubbles.
2. Registry 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ột mục ký tự đại diện groups: { "*": { ... } } (đặt allowAll = true), hoặc
   • một mục theo từng chat_id rõ ràng 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 theo từng 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ó. Chỉ giữ khối cũ làm nguồn sao chép cho đến khi đường dẫn mới được xác minh:
   {
     channels: {
       bluebubbles: {
         enabled: true,
         // ... existing config ...
       },
       imessage: {
         enabled: false, // turn on after the dry run below
         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. Thăm dò chạy thử — khởi động Gateway và xác nhận iMessage báo trạng thái khỏe mạnh:
   openclaw gateway
   openclaw channels status
   openclaw channels status --probe   # expect imessage.privateApi.available: true
   
   Vì imessage.enabled vẫn là false, chưa có lưu lượng iMessage đầu vào nào được định tuyến — nhưng --probe kiểm tra cầu nối để bạn phát hiện vấn đề về quyền/cài đặt trước khi chuyển đổi.
3. Chuyển đổi. Xóa cấu hình BlueBubbles và bật iMessage trong cùng một lần chỉnh sửa cấu hình:
   {
     channels: {
       imessage: { enabled: true /* ... */ },
     },
   }
   
   Khởi động lại Gateway. Lưu lượng iMessage đầu 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 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 từ 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 ở mức nhật ký mặc định. Nếu một trong hai xuất hiện, khối groups của bạn đang thiếu hoặc rỗng — xem “Bẫy đăng ký 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 hành động nào báo lỗi “iMessage <action> requires the imsg private API bridge”, hãy chạy lại imsg launch và làm mới channels status --probe.
7. Gỡ bỏ 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 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 theo mặc định session.dmScope=main; phiên nhóm vẫn tách biệt theo từng chat_id. Khóa phiên khác nhau (agent:<id>:imessage:group:<chat_id> so với khóa 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 vào 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

• iMessage — 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 đầu ra.