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

clawsweeper[bot] · clawsweeper[bot] · commit a371ee998efe · 2026-05-20T03:40:52.000Z
diff --git a/docs/channels/imessage.md b/docs/channels/imessage.md
@@ -127,7 +127,7 @@ Any `cliPath` wrapper or SSH proxy you put in front of `imsg` MUST behave like a
 - 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.
+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) is safe because it forwards OpenClaw's `cliPath` arguments such as `rpc` and `--db`. 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>
