iMessage

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.

​

Thiết lập nhanh

brew install steipete/tap/imsg
imsg rpc --help
imsg launch
openclaw channels status --probe

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

openclaw gateway

openclaw pairing list imessage
openclaw pairing approve imessage <CODE>

#!/usr/bin/env bash
exec 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.
• Cần Full Disk Access cho ngữ cảnh tiến trình chạy OpenClaw/imsg (truy cập DB Messages).
• Cần quyền Automation để 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 của 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.

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

​

Bật API riêng của imsg

• Chế độ cơ bản (mặc định, không cần thay đổi SIP): văn bản và phương tiện đi qua send, theo dõi/lịch sử đến, danh sách chat. Đây là những gì bạn có ngay từ đầu sau một lần brew install steipete/tap/imsg mới cùng các quyền macOS tiêu chuẩn ở trên.
• Chế độ API riêng: imsg tiêm một dylib trợ giúp vào Messages.app để gọi các hàm IMCore nội bộ. Chế độ này 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.

Các tính năng nâng cao như read, typing, launch, gửi phong phú được hỗ trợ bởi cầu nối, thay đổi tin nhắn và quản lý chat là tùy chọn bật. Chúng yêu cầu SIP bị tắt và một dylib trợ giúp được tiêm vào Messages.app. imsg launch từ chối tiêm khi SIP đang bật.

​

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/imsg
   imsg --version
   imsg 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: trình tự 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 nhấp Continue, rồi chạy csrutil disable. Thiết lập máy ảo dùng 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 quyền riêng 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 imsg launch hoặc các selectors cụ thể bắt đầu trả về false sau một lần nâng cấp lớn macOS, 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 đã bị 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 thao tác 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 cầu nối từ OpenClaw:
   openclaw channels status --probe
   
   Mục iMessage nên báo cáo works, và imsg status --json | jq '.selectors' nên 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ế kiểm soát 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 tác tử phản ánh những gì cầu nối thực sự có thể làm trên máy chủ này.

​

Khi bạn không thể tắt SIP

• 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à thao tác nhóm 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) với SIP tắt 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. 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: { "*": { "requireMention": true } },
    },
  },
}

{
  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 trò chuyện ACP

• Chạy /acp spawn codex --bind here bên trong DM hoặc cuộc trò chuyện nhóm được cho phép.
• Các tin nhắn sau này trong cùng cuộc trò chuyện iMessage đó sẽ được định tuyến đến phiên ACP đã 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.

• định danh DM đã chuẩn hóa như +15555550123 hoặc user@example.com
• chat_id:<id> (khuyến nghị cho liên kết nhóm ổn định)
• chat_guid:<guid>
• chat_identifier:<identifier>

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

​

Mô hình triển khai

{
  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 "$@"

​

Phương tiện, chia đoạn và đích gửi

imsg chats --limit 20

​

Hành động API riêng tư

{
  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

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

​

Gộp DM gửi tách (lệnh + URL trong một lần soạn)

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.

{
  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à nội dung tác nhân thấy

​

Bắt kịp sau thời gian Gateway ngừng hoạt động

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 hoạt động

​

Ngữ nghĩa con trỏ và thử lại

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

• Con trỏ tiến lên sau mỗi lần phân phối thành công và được giữ nguyên khi phân phối một hàng ném lỗi — lần khởi động tiếp theo thử lại cùng hàng đó từ con trỏ đã giữ.
• Sau maxFailureRetries lần ném lỗi liên tiếp với cùng guid, catchup ghi nhật ký warn và buộc con trỏ tiến qua tin nhắn bị kẹt để các lần khởi động sau có thể tiếp tục.
• Các guid đã bị bỏ cuộc trước đó sẽ bị bỏ qua ngay khi thấy (không cố phân phối) trong các lần chạy sau và được tính trong skippedGivenUp ở 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 <N> failures; advancing cursor past it
imessage catchup: fetched <X> rows across chats, capped to perRunLimit=<Y>

​

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

• Gateway chạy liên tục với watchdog tự động khởi động lại và 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ể phân phối ngữ cảnh cũ bất ngờ trong lần bật đầu tiên.

​

Khắc phục sự cố

imsg rpc --help
imsg status --json
openclaw channels status --probe

#!/usr/bin/env bash
exec ssh -T messages-mac imsg "$@"

openclaw channels status --probe --channel imessage

imsg chats --limit 1
imsg 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ợ
• Loại 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 chuyển đổi cấu hình và các bước chuyển đổi tuần tự
• 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à chặn theo 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à gia cố