openclaw - 💡(How to fix) Fix [Bug]: 2026.5.12 imsg RPC hangs when Gateway is started by launchd

Bug type

Behavior bug: bundled iMessage provider startup hangs before the first imsg rpc readiness response when Gateway is launched by the macOS LaunchAgent.

Beta release blocker

No.

Summary

On macOS, the bundled imessage channel works with Peter Steinberger's imsg when Gateway is started from an interactive user session, but the same provider times out when Gateway is started by the ai.openclaw.gateway LaunchAgent.

Steps to reproduce

1. Configure the bundled iMessage channel to use imsg.
2. Start Gateway through /Users/<user>/Library/LaunchAgents/ai.openclaw.gateway.plist.
3. Wait for the iMessage provider to start.
4. Check Gateway logs and channel status.

Expected behavior

The imsg rpc readiness check should return successfully under the LaunchAgent, as it does from the same user's interactive session. If launchd lacks a required macOS permission or session context, the provider should fail with an explicit actionable error.

Actual behavior

The iMessage provider starts an imsg rpc child process, but the readiness call times out. The child remains alive and has opened the Messages database files.

OpenClaw version

2026.5.12 (f066dd2)

Operating system

macOS 26.3.1

Install method

Source checkout with the live Gateway run by Homebrew Node 22 from the local built output.

Model

N/A - this occurs during channel startup before any model request.

Provider / routing chain

Gateway LaunchAgent -> bundled imessage channel -> /opt/homebrew/bin/imsg rpc -> /Users/<user>/Library/Messages/chat.db

The control path is the same Gateway and same imsg binary started from a detached interactive user session; that path works.

Additional provider/model setup details

imsg is installed from steipete/tap:

imsg 0.8.2

iMessage channel configuration:

channels.imessage.cliPath=/opt/homebrew/bin/imsg
channels.imessage.dbPath=/Users/<user>/Library/Messages/chat.db

The local checkout was also patched to call imsg rpc --json explicitly. That did not change the LaunchAgent hang.

Logs, screenshots, and evidence

Gateway log when started by launchd:

[imessage] [default] starting provider (/opt/homebrew/bin/imsg db=/Users/<user>/Library/Messages/chat.db)
[imessage] imsg rpc not ready after 10630ms (Error: imsg rpc timeout (chats.list))
[imessage] imsg rpc not ready after 30000ms (Error: imsg rpc timeout (chats.list))
[imessage] [default] channel exited: imsg rpc not ready (Error: imsg rpc timeout (chats.list))

The child process remains alive after the timeout:

/opt/homebrew/Cellar/imsg/0.8.2/libexec/imsg rpc --db /Users/<user>/Library/Messages/chat.db

Sampling the stuck child shows the main thread waiting in a Swift run loop. lsof shows the child has opened chat.db, chat.db-wal, and chat.db-shm, so this does not look like a simple Full Disk Access denial.

The same JSON-RPC call works directly under the same service environment:

printf '{"jsonrpc":"2.0","id":1,"method":"chats.list","params":{"limit":1}}\n' \
  | /opt/homebrew/bin/imsg rpc --db /Users/<user>/Library/Messages/chat.db

It also works when spawned through the same Homebrew Node binary from an interactive shell.

Detached session workaround:

$ openclaw channels status --probe --channel imessage
Gateway reachable.
- iMessage default: enabled, configured, running, works

Impact and severity

High for macOS installs that rely on the bundled iMessage channel and start Gateway with the default LaunchAgent. On this install, the iMessage channel fails every time Gateway is started by launchd and remains unavailable until Gateway is manually restarted from an interactive user session.

Additional information

Current workaround is to unload the LaunchAgent and run Gateway in a detached interactive session named openclaw-gateway.