Skip to Content
👋 欢迎来到 HowToUseMoltbot 快速入门
频道iMessage

iMessage（imsg）

状态：外部 CLI 集成。网关通过 stdio 上的 JSON-RPC 调用 imsg rpc。

快速设置（入门）

  1. 确保本机 Mac 已登录「信息」。
  2. 安装 imsg：
    • brew install steipete/tap/imsg
  3. 用 channels.imessage.cliPath 和 channels.imessage.dbPath 配置 Moltbot。
  4. 启动网关并批准所有 macOS 提示（自动化与「完全磁盘访问权限」）。

最小配置：

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

说明

  • 在 macOS 上由 imsg 支持的 iMessage 频道。
  • 确定性路由：回复始终发回 iMessage。
  • 私聊共享 agent 主会话；群组独立（agent:<agentId>:imessage:group:<chat_id>）。
  • 若多参与者会话以 is_group=false 到达，仍可通过 channels.imessage.groups 用 chat_id 将其视为群组隔离（见下方「类群组会话」）。

配置写入

默认允许 iMessage 写入由 /config set|unset 触发的配置更新（需 commands.config: true）。禁用方式：

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

要求

  • 已登录「信息」的 macOS。
  • Moltbot 与 imsg 需「完全磁盘访问权限」（访问 Messages 数据库）。
  • 发送时需自动化权限。
  • channels.imessage.cliPath 可指向任何代理 stdin/stdout 的命令（例如通过 SSH 到另一台 Mac 并运行 imsg rpc 的包装脚本）。

设置（快速路径）

  1. 确保本机 Mac 已登录「信息」。
  2. 配置 iMessage 并启动网关。

专用机器人 macOS 用户（独立身份）

若希望机器人以独立 iMessage 身份发送（并保持个人「信息」干净），可使用专用 Apple ID + 专用 macOS 用户。

  1. 创建专用 Apple ID（如 my-cool-bot@icloud.com）。
    • Apple 可能要求手机号用于验证/双重认证。
  2. 创建 macOS 用户（如 clawdshome）并登录。
  3. 在该 macOS 用户下打开「信息」，用机器人 Apple ID 登录 iMessage。
  4. 启用远程登录（系统设置 → 通用 → 共享 → 远程登录）。
  5. 安装 imsg：
    • brew install steipete/tap/imsg
  6. 配置 SSH，使 ssh <bot-macos-user>@localhost true 无需密码即可执行。
  7. 将 channels.imessage.accounts.bot.cliPath 指向以机器人用户运行 imsg 的 SSH 包装脚本。

首次运行说明：发送/接收可能需要在机器人 macOS 用户下批准 GUI（自动化与完全磁盘访问权限）。若 imsg rpc 卡住或退出，登录该用户（屏幕共享有帮助），运行一次 imsg chats --limit 1 / imsg send ...，批准提示后重试。示例包装脚本（chmod +x）。将 <bot-macos-user> 替换为实际 macOS 用户名：

#!/usr/bin/env bash
set -euo pipefail

# 首次可交互 SSH 一次以接受 host key：
#   ssh <bot-macos-user>@localhost true
exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
  "/usr/local/bin/imsg" "$@"

示例配置：

{
  channels: {
    imessage: {
      enabled: true,
      accounts: {
        bot: {
          name: "Bot",
          enabled: true,
          cliPath: "/path/to/imsg-bot",
          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db"
        }
      }
    }
  }
}

单账号时可用扁平选项（channels.imessage.cliPath、channels.imessage.dbPath）代替 accounts 映射。

远程/SSH 变体（可选）

若希望另一台 Mac 上的 iMessage，将 channels.imessage.cliPath 设为通过 SSH 在远程 macOS 主机上运行 imsg 的包装脚本。Moltbot 只需 stdio。示例包装脚本：

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

远程附件：当 cliPath 通过 SSH 指向远程主机时，Messages 数据库中的附件路径指向远程机器上的文件。Moltbot 可通过设置 channels.imessage.remoteHost 自动经 SCP 拉取：

{
  channels: {
    imessage: {
      cliPath: "~/imsg-ssh",                     // 到远程 Mac 的 SSH 包装
      remoteHost: "user@gateway-host",           // 用于 SCP 文件传输
      includeAttachments: true
    }
  }
}

若未设 remoteHost，Moltbot 会尝试从包装脚本中的 SSH 命令解析并自动检测。建议显式配置以保证稳定。

经 Tailscale 的远程 Mac（示例）

若网关运行在 Linux 主机/VM 上但 iMessage 必须在 Mac 上，Tailscale 是最简单的桥梁：网关经 tailnet 与 Mac 通信，通过 SSH 运行 imsg，并用 SCP 拉回附件。架构：

┌──────────────────────────────┐          SSH (imsg rpc)          ┌──────────────────────────┐
│ Gateway host (Linux/VM)      │──────────────────────────────────▶│ Mac with Messages + imsg │
│ - moltbot gateway           │          SCP (attachments)        │ - Messages signed in     │
│ - channels.imessage.cliPath  │◀──────────────────────────────────│ - Remote Login enabled   │
└──────────────────────────────┘                                   └──────────────────────────┘
              ▲
              │ Tailscale tailnet (hostname or 100.x.y.z)
              ▼
        user@gateway-host

具体配置示例（Tailscale 主机名）：

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.clawdbot/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db"
    }
  }
}

示例包装脚本（~/.clawdbot/scripts/imsg-ssh）：

#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

说明：

  • 确保 Mac 已登录「信息」且已启用远程登录。
  • 使用 SSH 密钥使 ssh bot@mac-mini.tailnet-1234.ts.net 无需提示即可执行。
  • remoteHost 应与 SSH 目标一致，以便 SCP 拉取附件。

多账号：使用 channels.imessage.accounts，每账号单独配置并可设 name。共享模式见 配置。不要提交 ~/.clawdbot/moltbot.json（通常含 token）。

访问控制（私聊 + 群组）

私聊：

  • 默认：channels.imessage.dmPolicy = "pairing"。
  • 未知发件人收到配对码；批准前消息被忽略（配对码 1 小时后过期）。
  • 批准方式：
    • moltbot pairing list imessage
    • moltbot pairing approve imessage <CODE>
  • 配对为 iMessage 私聊的默认 token 交换。详见 配对。

群组：

  • channels.imessage.groupPolicy = open | allowlist | disabled。
  • channels.imessage.groupAllowFrom 在设为 allowlist 时控制谁可在群组中触发。
  • 提及门控使用 agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns），因 iMessage 无原生 @ 提及元数据。
  • 多 agent 覆盖：在 agents.list[].groupChat.mentionPatterns 上设每 agent 规则。

行为说明

  • imsg 流式推送消息事件；网关将其规范为统一频道信封。
  • 回复始终路由回同一 chat id 或 handle。

类群组会话（is_group=false）

部分 iMessage 会话可能有多参与者但仍以 is_group=false 到达，取决于「信息」如何存储会话标识。若在 channels.imessage.groups 下显式配置某个 chat_id，Moltbot 会将该会话视为「群组」，用于：

  • 会话隔离（独立会话键 agent:<agentId>:imessage:group:<chat_id>）
  • 群组白名单 / @ 提及行为

示例：

{
  channels: {
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "42": { "requireMention": false }
      }
    }
  }
}

适用于希望某条会话有独立人格/模型时（见 多 agent 路由）。文件系统隔离见 沙箱。

媒体与限制

  • 可选通过 channels.imessage.includeAttachments 摄入附件。
  • 媒体上限：channels.imessage.mediaMaxMb。

限制

  • 出站文本按 channels.imessage.textChunkLimit 分块（默认 4000）。
  • 可选按换行分块：设 channels.imessage.chunkMode="newline" 在按长度分块前按空行（段落边界）拆分。
  • 媒体上传受 channels.imessage.mediaMaxMb 限制（默认 16）。

寻址 / 投递目标

稳定路由建议用 chat_id：

  • chat_id:123（推荐）
  • chat_guid:...
  • chat_identifier:...
  • 直接 handle：imessage:+1555 / sms:+1555 / user@example.com

列出会话：

imsg chats --limit 20

配置参考（iMessage）

完整配置见 配置。本频道选项：

  • channels.imessage.enabled：是否启动频道。
  • channels.imessage.cliPath：imsg 路径。
  • channels.imessage.dbPath：Messages 数据库路径。
  • channels.imessage.remoteHost：当 cliPath 指向远程 Mac 时用于 SCP 附件传输的 SSH 主机（如 user@gateway-host）。未设时从 SSH 包装脚本自动检测。
  • channels.imessage.service：imessage | sms | auto。
  • channels.imessage.region：SMS 区域。
  • channels.imessage.dmPolicy：pairing | allowlist | open | disabled（默认 pairing）。
  • channels.imessage.allowFrom：私聊白名单（handle、邮箱、E.164 号码或 chat_id:*）。open 需 "*"。iMessage 无用户名；用 handle 或会话目标。
  • channels.imessage.groupPolicy：open | allowlist | disabled（默认 allowlist）。
  • channels.imessage.groupAllowFrom：群组发件人白名单。
  • channels.imessage.historyLimit / channels.imessage.accounts.*.historyLimit：作为上下文的群组消息上限（0 禁用）。
  • channels.imessage.dmHistoryLimit：私聊历史轮次上限。每用户覆盖：channels.imessage.dms["<handle>"].historyLimit。
  • channels.imessage.groups：每群组默认与白名单（用 "*" 表示全局默认）。
  • channels.imessage.includeAttachments：是否将附件纳入上下文。
  • channels.imessage.mediaMaxMb：入站/出站媒体上限（MB）。
  • channels.imessage.textChunkLimit：出站分块大小（字符）。
  • channels.imessage.chunkMode：length（默认）或 newline，在按长度分块前按空行（段落边界）拆分。

相关全局选项：

  • agents.list[].groupChat.mentionPatterns（或 messages.groupChat.mentionPatterns）。
  • messages.responsePrefix。
最后更新于:
GrammyLine