跳转至

故障排除

针对 iMessage 通道的症状优先修复方案，以及配置参考链接。

故障排查

imsg 未找到或 RPC 不受支持

验证二进制文件和 RPC 支持：

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

如果探测报告 RPC 不受支持，请更新 imsg。如果私有 API 操作不可用，请在已登录的 macOS 用户会话中运行 imsg launch，然后再次探测。如果 Gateway 未在 macOS 上运行，请改用 Remote Mac over SSH 设置，而不是默认的本地 imsg 路径。

消息能发出，但入站 iMessage 未到达 
首先确认消息是否已到达本地 Mac。如果 `chat.db` 没有变化，即使 `imsg status --json` 报告桥接状态正常，OpenClaw 也无法接收该消息。

imsg chats --limit 10 --json
imsg watch --chat-id <chat-id> --json
sqlite3 ~/Library/Messages/chat.db \
  "select datetime(max(date)/1000000000 + 978307200, 'unixepoch', 'localtime'), max(ROWID) from message;"

如果从手机发送的消息没有创建新行，请先修复 macOS Messages 和 Apple Push 层，再更改 OpenClaw 配置。通常一次性刷新服务即可：

launchctl kickstart -k system/com.apple.apsd
launchctl kickstart -k gui/$(id -u)/com.apple.CommCenter
launchctl kickstart -k gui/$(id -u)/com.apple.identityservicesd
launchctl kickstart -k gui/$(id -u)/com.apple.imagent
imsg launch
openclaw gateway restart

从手机发送一条新的 iMessage，并在调试 OpenClaw 会话之前，确认出现了新的 `chat.db` 行或 `imsg watch` 事件。不要将此作为周期性桥接重启循环运行；在活动工作期间反复执行 `imsg launch` 并重启 gateway，可能会中断投递并搁置正在进行的通道运行。
Gateway 未在 macOS 上运行 
默认的 `cliPath: "imsg"` 必须在已登录 Messages 的 Mac 上运行。在 Linux 或 Windows 上，请将 `channels.imessage.cliPath` 设置为一个包装脚本，该脚本通过 SSH 连接到那台 Mac 并运行 `imsg "$@"`。

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

然后运行：

openclaw channels status --probe --channel imessage
DM 被忽略

检查：

  • channels.imessage.dmPolicy
  • channels.imessage.allowFrom
  • 配对审批（openclaw pairing list imessage）
群消息被忽略

检查：

  • channels.imessage.groupPolicy
  • channels.imessage.groupAllowFrom
  • channels.imessage.groups 允许列表行为
  • 提及门控：显式模式或路由代理的身份名称/表情符号；在生效的根或账户 groups 映射中，为该聊天设置 requireMention: false，以处理来自允许发送者的所有消息
远程附件失败

检查：

  • channels.imessage.remoteHost
  • channels.imessage.remoteAttachmentRoots
  • 从 gateway 主机进行 SSH/SCP 密钥认证
  • gateway 主机上的 ~/.ssh/known_hosts 中存在主机密钥
  • 运行 Messages 的 Mac 上远程路径可读
错过了 macOS 权限提示

请在同一用户/会话上下文的交互式 GUI 终端中重新运行，并批准提示：

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

确认运行 OpenClaw/imsg 的进程上下文已授予 Full Disk Access + Automation。

配置参考指针

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw