Summary

The iMessage docs explain that channels.imessage.cliPath can point to an SSH/custom wrapper, but they do not currently call out an important interoperability requirement: the wrapper/proxy must forward JSON-RPC stdin/stdout incrementally. It must not wait for EOF or a large fixed-size buffer before forwarding data.

A wrapper that reads with a large blocking read(N) can make small JSON-RPC messages such as chats.list sit indefinitely, producing symptoms like imsg rpc timeout (chats.list) even though imsg rpc itself is working.

Observed Behavior

With a custom stdio bridge wrapper:

• OpenClaw started imsg rpc successfully.
• iMessage channel health could show as configured/running or repeatedly restart.
• JSON-RPC requests such as chats.list timed out.
• The underlying issue was the wrapper buffering small stdin/stdout frames until EOF or a large buffer filled.
• Changing the wrapper to forward data as soon as bytes/lines were available fixed the RPC timeout.

Expected Documentation

The iMessage remote-wrapper docs should explicitly state that a cliPath wrapper must behave like a transparent stdio pipe for long-lived JSON-RPC:

• forward each stdin chunk/line promptly
• forward stdout chunks/lines promptly
• preserve newlines
• avoid waiting for EOF before forwarding
• avoid fixed-size blocking reads that can starve small JSON-RPC frames
• keep stderr separate from JSON-RPC stdout

Suggested Location

This likely belongs in docs/channels/imessage.md near the "Remote Mac over SSH" / custom cliPath wrapper section.

Why It Matters

The failure mode looks like an OpenClaw/iMessage channel outage (imsg rpc timeout), but the root cause is wrapper buffering. A short note would make custom remote iMessage deployments much easier to diagnose and avoid.