Chuyển đến nội dung chính

​
iMessage (cũ: imsg)

Đối với các triển khai iMessage mới, hãy sử dụng BlueBubbles.Tích hợp imsg là cũ và có thể bị loại bỏ trong các phiên bản tương lai.
Trạng thái: tích hợp CLI bên ngoài cũ. Gateway khởi chạy imsg rpc và giao tiếp qua JSON-RPC trên stdio (không có daemon/port riêng).

BlueBubbles (khuyến nghị)

Đường dẫn iMessage ưu tiên cho các thiết lập mới.

Ghép nối

iMessage DMs mặc định ở chế độ ghép nối.

Tham khảo cấu hình

Tham khảo đầy đủ các trường iMessage.

​
Thiết lập nhanh

1

Cài đặt và xác minh imsg

brew install steipete/tap/imsg
imsg rpc --help
2

Cấu hình OpenClaw

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "/usr/local/bin/imsg",
      dbPath: "/Users/<you>/Library/Messages/chat.db",
    },
  },
}
3

Khởi động gateway

openclaw gateway
4

Phê duyệt ghép nối DM đầu tiên (dmPolicy mặc định)

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
Yêu cầu ghép nối hết hạn sau 1 giờ.

​
Yêu cầu và quyền (macOS)

  • Messages phải được đăng nhập trên Mac chạy imsg.
  • Quyền truy cập toàn bộ ổ đĩa là cần thiết cho ngữ cảnh tiến trình chạy OpenClaw/imsg (truy cập DB Messages).
  • Quyền tự động hóa là cần thiết để gửi tin nhắn qua Messages.app.
Quyền được cấp theo ngữ cảnh tiến trình. Nếu gateway chạy không có giao diện (LaunchAgent/SSH), hãy chạy một lệnh tương tác một lần trong cùng ngữ cảnh để kích hoạt các thông báo:
imsg chats --limit 1
# hoặc
imsg send <handle> "test"

​
Kiểm soát truy cập và định tuyến

channels.imessage.dmPolicy kiểm soát tin nhắn trực tiếp:
  • pairing (mặc định)
  • allowlist
  • open (yêu cầu allowFrom bao gồm "*")
  • disabled
Trường danh sách cho phép: channels.imessage.allowFrom.Các mục trong danh sách cho phép có thể là handles hoặc mục tiêu chat (chat_id:*, chat_guid:*, chat_identifier:*).

​
Mẫu triển khai

Sử dụng một Apple ID và người dùng macOS chuyên dụng để lưu lượng bot được tách biệt khỏi hồ sơ Messages cá nhân của bạn.Quy trình điển hình:
  1. Tạo/đăng nhập một người dùng macOS chuyên dụng.
  2. Đăng nhập vào Messages với Apple ID bot trong người dùng đó.
  3. Cài đặt imsg trong người dùng đó.
  4. Tạo SSH wrapper để OpenClaw có thể chạy imsg trong ngữ cảnh người dùng đó.
  5. Chỉ định channels.imessage.accounts.<id>.cliPath và .dbPath vào hồ sơ người dùng đó.
Lần chạy đầu tiên có thể yêu cầu phê duyệt GUI (Tự động hóa + Truy cập toàn bộ ổ đĩa) trong phiên người dùng bot đó.
Cấu trúc phổ biến:
  • gateway chạy trên Linux/VM
  • iMessage + imsg chạy trên một Mac trong mạng tailnet của bạn
  • cliPath wrapper sử dụng SSH để chạy imsg
  • remoteHost cho phép lấy đính kèm qua SCP
Ví dụ:
{
  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 bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
Sử dụng khóa SSH để cả SSH và SCP không cần tương tác. Đảm bảo khóa host được tin cậy trước (ví dụ ssh bot@mac-mini.tailnet-1234.ts.net) để known_hosts được điền.
iMessage hỗ trợ cấu hình theo từng tài khoản dưới channels.imessage.accounts.Mỗi tài khoản có thể ghi đè các trường như cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, cài đặt lịch sử và danh sách cho phép gốc đính kèm.

​
Media, chia nhỏ, và mục tiêu gửi

  • việc tiếp nhận đính kèm đầu vào là tùy chọn: channels.imessage.includeAttachments
  • đường dẫn đính kèm từ xa có thể được lấy qua SCP khi remoteHost được thiết lập
  • đường dẫn đính kèm phải khớp với các gốc được phép:
    • channels.imessage.attachmentRoots (cục bộ)
    • channels.imessage.remoteAttachmentRoots (chế độ SCP từ xa)
    • mẫu gốc mặc định: /Users/*/Library/Messages/Attachments
  • SCP sử dụng kiểm tra khóa host nghiêm ngặt (StrictHostKeyChecking=yes)
  • kích thước media gửi đi sử dụng channels.imessage.mediaMaxMb (mặc định 16 MB)
  • giới hạn chia nhỏ văn bản: channels.imessage.textChunkLimit (mặc định 4000)
  • chế độ chia nhỏ: channels.imessage.chunkMode
    • length (mặc định)
    • newline (chia theo đoạn đầu tiên)
Mục tiêu rõ ràng được ưu tiên:
  • chat_id:123 (khuyến nghị cho định tuyến ổn định)
  • chat_guid:...
  • chat_identifier:...
Các mục tiêu handle cũng được hỗ trợ:
  • imessage:+1555...
  • sms:+1555...
  • user@example.com
imsg chats --limit 20

​
Ghi cấu hình

iMessage cho phép ghi cấu hình khởi tạo từ kênh theo mặc định (cho /config set|unset khi commands.config: true). Vô hiệu hóa: 
{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

​
Khắc phục sự cố

Xác minh binary và hỗ trợ RPC:
imsg rpc --help
openclaw channels status --probe
Nếu probe báo cáo RPC không được hỗ trợ, hãy cập nhật imsg.
Kiểm tra:
  • channels.imessage.dmPolicy
  • channels.imessage.allowFrom
  • phê duyệt ghép nối (openclaw pairing list imessage)
Kiểm tra:
  • channels.imessage.groupPolicy
  • channels.imessage.groupAllowFrom
  • hành vi danh sách cho phép channels.imessage.groups
  • cấu hình mẫu đề cập (agents.list[].groupChat.mentionPatterns)
Kiểm tra:
  • channels.imessage.remoteHost
  • channels.imessage.remoteAttachmentRoots
  • xác thực khóa SSH/SCP từ máy chủ gateway
  • khóa host tồn tại trong ~/.ssh/known_hosts trên máy chủ gateway
  • khả năng đọc đường dẫn từ xa trên Mac chạy Messages
Chạy lại trong một terminal GUI tương tác trong cùng ngữ cảnh người dùng/phiên và phê duyệt các thông báo:
imsg chats --limit 1
imsg send <handle> "test"
Xác nhận Truy cập toàn bộ ổ đĩa + Tự động hóa được cấp cho ngữ cảnh tiến trình chạy OpenClaw/imsg.

​
Tham khảo cấu hình

Last modified on March 22, 2026