mcpField
I
imsg-rpc

imsg-rpc

github.com/joelhooks云与 DevOps6535 次安装1 天前更新
代码仓库

关于 imsg-rpc

imsg-rpc 是用于管理 launchd 服务的技能，该服务通过 Unix socket 将 JoelClaw Gateway 守护进程连接到 iMessage。内容涵盖服务健康检查、应用构建与签名、完全磁盘访问设置及 socket 故障排查。

主要功能

  1. 01管理 launchd 服务
  2. 02检查 socket 与 Gateway 健康状态
  3. 03构建并签名 imsg 应用
  4. 04设置完全磁盘访问权限
  5. 05排查 JSON-RPC socket 问题

适用场景

  1. 01检查 iMessage Gateway 连通性
  2. 02在新机器上设置服务
  3. 03恢复缺失或无响应的 socket
  4. 04诊断完全磁盘访问故障

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/joelhooks/joelclaw --skill imsg-rpc

安装后在 Claude Code 中输入/imsg-rpc确认已加载。

附带文件agents/openai.yaml

详细介绍

imsg-rpc 技能

管理 com.joel.imsg-rpc launchd 服务，通过 Unix 套接字将网关守护进程连接到 iMessage。

架构（ADR-0121）

gateway daemon (bun, no FDA)
    ↕ JSON-RPC over /tmp/imsg.sock
imsg-rpc (com.joel.imsg-rpc launchd agent, has FDA)
    ↕ SQLite reads
~/Library/Messages/chat.db
  • 源代码：~/Code/steipete/imsg（由我们维护，可自由修改）
  • 构建二进制文件：~/Code/steipete/imsg/bin/imsg
  • 启动二进制文件：/Applications/imsg-rpc.app/Contents/MacOS/imsg
  • 套接字：/tmp/imsg.sock
  • launchd plist：~/Library/LaunchAgents/com.joel.imsg-rpc.plist
  • 日志：/tmp/joelclaw/imsg-rpc.{log,err}
  • 网关频道：packages/gateway/src/channels/imessage.ts

状态检查

launchctl print gui/$(id -u)/com.joel.imsg-rpc | rg "state =|pid =|runs =|last exit code"
lsof -p "$(launchctl print gui/$(id -u)/com.joel.imsg-rpc | awk '/pid =/{print $3; exit}')" | rg "imsg.sock|chat.db"
lsof -nP -U | rg "imsg.sock|com.joel.gateway|/tmp/imsg.sock"  # gateway socket peer
tail -10 /tmp/joelclaw/gateway.log | rg imessage

健康状态：PID 存在，退出代码为 0，网关显示 watch.subscribe OK。

重启

launchctl unload ~/Library/LaunchAgents/com.joel.imsg-rpc.plist
launchctl load ~/Library/LaunchAgents/com.joel.imsg-rpc.plist

重新构建 imsg

始终使用 build-local.sh，而不是 make build，这样签名才能保持稳定，并确保 /Applications/imsg-rpc.app 与源代码构建保持同步：

cd ~/Code/steipete/imsg && ./build-local.sh

build-local.sh 现在会：

  • 构建 bin/imsg
  • 使用 imsg Local Signing 签名
  • 通过 scripts/install-rpc-app.sh 更新并签名 /Applications/imsg-rpc.app

设置 FDA（新设备）

imsg 二进制文件需要“完全磁盘访问”权限。macOS 要求代码签名可验证，才能授予此权限。

1. 使用现有签名身份

检查可用的代码签名身份，无需导出密钥。身份有效时，复用服务已采用的身份。如需新身份，请使用获准的钥匙串流程；私钥必须保留在钥匙串中，或存放在任务专用且权限严格的临时目录中，并在完成后清理。不要使用共享的固定临时文件名，也不要使用硬编码的导出密码。签名前验证身份和信任状态。

2. 构建并签名
cd ~/Code/steipete/imsg && ./build-local.sh
3. 在“系统设置”中授予 FDA
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"
  • 点击 +
  • 按 ⌘⇧G，粘贴 /Applications/imsg-rpc.app，然后按 Enter
  • 切换为 开启
4. 加载服务
launchctl load ~/Library/LaunchAgents/com.joel.imsg-rpc.plist

验证：运行 tail -f /tmp/joelclaw/gateway.log | grep imessage，应显示 watch.subscribe OK。

故障排查

imsg-rpc.log 中出现 permissionDenied

缺少 FDA，或 csreq 不匹配。检查：

sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db \
  "SELECT client, auth_value FROM access WHERE client LIKE '%imsg%';"
# auth_value 2 = allowed, 0 = denied

/usr/bin/log show --last 10m --style compact \
  --predicate 'process == "tccd" && (eventMessage CONTAINS "com.steipete.imsg" || eventMessage CONTAINS "kTCCServiceSystemPolicyAllFiles")' \
  | tail -80

如果被拒绝（0）：前往“系统设置”→“完全磁盘访问”，将 imsg 切换为开启。 如果缺少：重新执行 FDA 设置步骤 3。 如果 tccd 对 /Applications/imsg-rpc.app/Contents/MacOS/imsg 显示 AUTHREQ_RESULT ... authValue=2，则表示已授予 FDA。

套接字存在，但网关无法订阅

imsg-rpc 在接受连接后崩溃了。检查 /tmp/joelclaw/imsg-rpc.err。重启服务。

出现 connect ENOENT /tmp/imsg.sock，但 launchd 显示服务正在运行

守护进程可以继续运行，但 Unix 套接字路径已被取消链接。必须重新创建套接字路径，网关才能连接。

launchctl kickstart -k gui/$(id -u)/com.joel.imsg-rpc
ls -l /tmp/imsg.sock

网关现在会在反复出现 ENOENT 时尝试自动修复，但在故障期间，手动 kickstart 是最快的恢复方式。

重新构建后切换 FDA 没有帮助

你可能重新构建时没有更新应用包。重新运行：

cd ~/Code/steipete/imsg && ./build-local.sh
imsg-rpc 不断重启（退出代码 1）

可能是 FDA 授权被拒绝。在终端中运行以进行测试：

/Applications/imsg-rpc.app/Contents/MacOS/imsg chats --limit 1

如果运行成功，但 launchd 仍失败 → FDA 条目对应的路径或签名有误。

JSON-RPC 协议参考

网关通过 /tmp/imsg.sock 使用以下方法：

// Subscribe to incoming messages
{"jsonrpc":"2.0","method":"watch.subscribe","params":{"participants":["handle"]},"id":1}

// Send a message
{"jsonrpc":"2.0","method":"send","params":{"to":"handle","text":"..."},"id":2}

// Inbound notification format
{"jsonrpc":"2.0","method":"message","params":{"subscription":1,"message":{...}}}

文件

路径用途
~/Code/steipete/imsg/imsg 源代码（由我们维护）
~/Code/steipete/imsg/bin/imsg已构建的二进制文件
/Applications/imsg-rpc.applaunchd 进程的 FDA 目标应用包
~/Code/steipete/imsg/build-local.sh构建 + 签名 + 同步应用
~/Code/steipete/imsg/scripts/install-rpc-app.sh创建并签名 /Applications/imsg-rpc.app
~/Library/LaunchAgents/com.joel.imsg-rpc.plistlaunchd 服务（不在 git 中）
packages/gateway/src/channels/imessage.ts网关套接字客户端
apps/web/content/adrs/0121-imsg-rpc-socket-daemon.mdADR

评论

支持 Markdown