iMessage

Đối với các triển khai iMessage mới, hãy dùng BlueBubbles.Tích hợp imsg là di sản và có thể bị xóa trong một bản phát hành tương lai.

Trạng thái: tích hợp CLI bên ngoài di sản. Gateway khởi chạy imsg rpc và giao tiếp qua JSON-RPC trên stdio (không có daemon/cổng riêng).

BlueBubbles (được khuyến nghị)

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

Ghép nối

Tin nhắn trực tiếp iMessage mặc định dùng chế độ ghép nối.

Tham chiếu cấu hình

Tham chiếu đầy đủ cho các trường iMessage.

Thiết lập nhanh

Mac cục bộ (đường dẫn nhanh)
Mac từ xa qua SSH

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

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

Cấu hình OpenClaw

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

Khởi động gateway

openclaw gateway

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ờ.

OpenClaw chỉ yêu cầu một cliPath tương thích với stdio, vì vậy bạn có thể trỏ cliPath tới một script wrapper dùng SSH vào Mac từ xa và chạy imsg.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Cấu hình được khuyến nghị khi bật tệp đính kèm:

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

Nếu remoteHost chưa được đặt, OpenClaw sẽ cố gắng tự động phát hiện bằng cách phân tích script wrapper SSH. remoteHost phải là host hoặc user@host (không có khoảng trắng hoặc tùy chọn SSH). OpenClaw dùng kiểm tra host-key nghiêm ngặt cho SCP, nên khóa host chuyển tiếp phải đã tồn tại trong ~/.ssh/known_hosts. Đường dẫn tệp đính kèm được xác thực theo các gốc được phép (attachmentRoots / remoteAttachmentRoots).

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

Messages phải được đăng nhập trên Mac chạy imsg.
Cần Full Disk Access cho ngữ cảnh tiến trình chạy OpenClaw/imsg (truy cập CSDL Messages).
Cần quyền Automation để gửi tin nhắn qua Messages.app.

Quyền được cấp theo từng ngữ cảnh tiến trình. Nếu gateway chạy headless (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 lời nhắc:

imsg chats --limit 1
# or
imsg send <handle> "test"

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

Chính sách DM
Chính sách nhóm + nhắc đến
Phiên và phản hồi xác định

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.Mục trong danh sách cho phép có thể là handle hoặc mục tiêu chat (chat_id:*, chat_guid:*, chat_identifier:*).

channels.imessage.groupPolicy kiểm soát xử lý nhóm:

allowlist (mặc định khi được cấu hình)
open
disabled

Danh sách cho phép người gửi nhóm: channels.imessage.groupAllowFrom.Dự phòng runtime: nếu groupAllowFrom chưa được đặt, các kiểm tra người gửi nhóm iMessage sẽ dùng dự phòng allowFrom khi có. Ghi chú runtime: nếu channels.imessage hoàn toàn bị thiếu, runtime sẽ dùng dự phòng groupPolicy="allowlist" và ghi cảnh báo (ngay cả khi channels.defaults.groupPolicy được đặt).Kiểm soát bằng nhắc đến cho nhóm:

iMessage không có siêu dữ liệu nhắc đến gốc
phát hiện nhắc đến dùng các mẫu regex (agents.list[].groupChat.mentionPatterns, dự phòng messages.groupChat.mentionPatterns)
khi không có mẫu được cấu hình, không thể thực thi kiểm soát bằng nhắc đến

Lệnh điều khiển từ người gửi được ủy quyền có thể bỏ qua kiểm soát bằng nhắc đến trong nhóm.

DM dùng định tuyến trực tiếp; nhóm dùng định tuyến nhóm.
Với session.dmScope=main mặc định, DM iMessage được gom vào phiên chính của agent.
Phiên nhóm được cô lập (agent:<agentId>:imessage:group:<chat_id>).
Phản hồi được định tuyến lại về iMessage bằng siêu dữ liệu kênh/mục tiêu gốc.

Hành vi luồng giống nhóm:Một số luồng iMessage có nhiều người tham gia có thể đến với is_group=false. Nếu chat_id đó được cấu hình rõ ràng trong channels.imessage.groups, OpenClaw sẽ xem đó là lưu lượng nhóm (kiểm soát nhóm + cô lập phiên nhóm).

Liên kết cuộc trò chuyện ACP

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

Hỗ trợ liên kết bền vững được cấu hình 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:

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 Agent ACP để biết hành vi liên kết ACP dùng chung.

Mẫu triển khai

Người dùng macOS bot chuyên dụng (danh tính iMessage riêng)

Dùng một Apple ID và người dùng macOS chuyên dụng để lưu lượng bot được cô lập khỏi hồ sơ Messages cá nhân của bạn.Luồng điển hình:

Tạo/đăng nhập một người dùng macOS chuyên dụng.
Đăng nhập vào Messages bằng Apple ID của bot trong người dùng đó.
Cài đặt imsg trong người dùng đó.
Tạo SSH wrapper để OpenClaw có thể chạy imsg trong ngữ cảnh người dùng đó.
Trỏ channels.imessage.accounts.<id>.cliPath và .dbPath tới hồ sơ người dùng đó.

Lần chạy đầu tiên có thể yêu cầu phê duyệt GUI (Automation + Full Disk Access) trong phiên người dùng bot đó.

Mac từ xa qua Tailscale (ví dụ)

Tô pô phổ biến:

gateway chạy trên Linux/VM
iMessage + imsg chạy trên một Mac trong tailnet của bạn
wrapper cliPath dùng SSH để chạy imsg
remoteHost bật tải tệp đí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 "$@"

Dùng khóa SSH để cả SSH và SCP đều không 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.

Mẫu nhiều tài khoản

iMessage hỗ trợ cấu hình theo từng tài khoản trong channels.imessage.accounts.Mỗi tài khoản có thể ghi đè các trường như cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, thiết lập lịch sử và danh sách cho phép gốc tệp đính kèm.

Phương tiện, chia đoạn và mục tiêu gửi

Tệp đính kèm và phương tiện

tiếp nhận tệp đính kèm đầu vào là tùy chọn: channels.imessage.includeAttachments
đường dẫn tệp đính kèm từ xa có thể được tải qua SCP khi remoteHost được đặt
đường dẫn tệp đí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 dùng kiểm tra host-key nghiêm ngặt (StrictHostKeyChecking=yes)
kích thước phương tiện đầu ra dùng channels.imessage.mediaMaxMb (mặc định 16 MB)

Chia đoạn đầu ra

giới hạn đoạn văn bản: channels.imessage.textChunkLimit (mặc định 4000)
chế độ chia đoạn: channels.imessage.chunkMode
- length (mặc định)
- newline (chia ưu tiên đoạn văn)

Định dạng địa chỉ

Mục tiêu rõ ràng được ưu tiên:

chat_id:123 (được khuyến nghị để định tuyến ổn định)
chat_guid:...
chat_identifier:...

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

Khắc phục sự cố

Không tìm thấy imsg hoặc RPC không được hỗ trợ

Xác thực 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.

DM bị bỏ qua

Kiểm tra:

channels.imessage.dmPolicy
channels.imessage.allowFrom
phê duyệt ghép nối (openclaw pairing list imessage)

Tin nhắn nhóm bị bỏ qua

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 nhắc đến (agents.list[].groupChat.mentionPatterns)

Tệp đính kèm từ xa thất bại

Kiểm tra:

channels.imessage.remoteHost
channels.imessage.remoteAttachmentRoots
xác thực khóa SSH/SCP từ host gateway
khóa host tồn tại trong ~/.ssh/known_hosts trên host gateway
khả năng đọc đường dẫn từ xa trên Mac chạy Messages

Đã bỏ lỡ lời nhắc quyền macOS

Chạy lại trong terminal GUI tương tác trong cùng ngữ cảnh người dùng/phiên và phê duyệt lời nhắc:

imsg chats --limit 1
imsg send <handle> "test"

Xác nhận Full Disk Access + Automation đã được cấp cho ngữ cảnh tiến trình chạy OpenClaw/imsg.

Con trỏ tham chiếu cấu hình

Liên quan

Tổng quan kênh — tất cả kênh được hỗ trợ
Ghép nối — xác thực DM và luồng ghép nối
Nhóm — hành vi chat nhóm và kiểm soát bằ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

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

BlueBubbles (được khuyến nghị)

Ghép nối

Tham chiếu cấu hình

Thiết lập nhanh

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

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

Liên kết cuộc trò chuyện ACP

Mẫu triển khai

Phương tiện, chia đoạn và mục tiêu gửi

Ghi cấu hình

Khắc phục sự cố

Con trỏ tham chiếu cấu hình

Liên quan

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Documentation Index

BlueBubbles (được khuyến nghị)

Ghép nối

Tham chiếu cấu hình

​Thiết lập nhanh

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

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

​Liên kết cuộc trò chuyện ACP

​Mẫu triển khai

​Phương tiện, chia đoạn và mục tiêu gửi

​Ghi cấu hình

​Khắc phục sự cố

​Con trỏ tham chiếu cấu hình

​Liên quan

Thiết lập nhanh

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

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

Liên kết cuộc trò chuyện ACP

Mẫu triển khai

Phương tiện, chia đoạn và mục tiêu gửi

Ghi cấu hình

Khắc phục sự cố

Con trỏ tham chiếu cấu hình

Liên quan