docs(imessage): warn that cliPath wrappers must stream JSON-RPC stdio (#84330)

HCL · HCL · commit 44c7bae10d4d · 2026-05-20T06:38:48.000+08:00
A custom `cliPath` wrapper or SSH proxy in front of `imsg` must behave
like a transparent stdio pipe for long-lived JSON-RPC: small newline-
framed messages can sit indefinitely if the wrapper buffers stdin
until EOF or a large block fills. The visible symptom is
`imsg rpc timeout (chats.list)` or repeated channel restarts even
though `imsg rpc` is healthy.

Add a &lt;Warning&gt; block in the 'Remote Mac over SSH' Tab listing the
six interoperability requirements the issue calls out, and note that
filter pipelines like `ssh host imsg | grep ...` need `stdbuf -oL`
on every stage to stay safe.
diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md
@@ -118,6 +118,18 @@ exec ssh -T gateway-host imsg "$@"
     OpenClaw uses strict host-key checking for SCP, so the relay host key must already exist in `~/.ssh/known_hosts`.
     Attachment paths are validated against allowed roots (`attachmentRoots` / `remoteAttachmentRoots`).
 
+<Warning>
+Any `cliPath` wrapper or SSH proxy you put in front of `imsg` MUST behave like a transparent stdio pipe for long-lived JSON-RPC. OpenClaw exchanges small newline-framed JSON-RPC messages over the wrapper's stdin/stdout for the lifetime of the channel:
+
+- Forward each stdin chunk/line **as soon as bytes are available** — don't wait for EOF.
+- Forward each stdout chunk/line promptly in the reverse direction.
+- Preserve newlines.
+- Avoid fixed-size blocking reads (`read(4096)`, `cat | buffer`, default shell `read`) that can starve small frames.
+- Keep stderr separate from the JSON-RPC stdout stream.
+
+A wrapper that buffers stdin until a large block fills will produce symptoms that look like an iMessage outage — `imsg rpc timeout (chats.list)` or repeated channel restarts — even though `imsg rpc` itself is healthy. `ssh -T host imsg "$@"` (above) and `socat - EXEC:"ssh host imsg",pty,stderr` are safe. Pipelines like `ssh host imsg | grep -v '^DEBUG'` are NOT — line-buffered tools can still hold frames; use `stdbuf -oL -eL` on every stage if you must filter.
+</Warning>
+
   </Tab>
 </Tabs>
 
