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

• Repository: openclaw/openclaw
• Author: hclsys
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/84347

Description (problem / solution / changelog)

Fixes #84330.

docs/channels/imessage.md documents that channels.imessage.cliPath can be pointed at an SSH/custom wrapper but doesn't call out a critical interoperability requirement: the wrapper must forward JSON-RPC stdin/stdout incrementally. The OpenClaw iMessage channel exchanges small newline-framed JSON-RPC frames over the wrapper's stdio for the channel's entire lifetime. A wrapper that reads with a large blocking read(N) or buffers stdin until EOF will make small frames like chats.list sit indefinitely, producing symptoms that look exactly like an iMessage outage (imsg rpc timeout (chats.list), repeated channel restarts) even though imsg rpc itself is fine.

Changes

• docs/channels/imessage.md: add a <Warning> block inside the "Remote Mac over SSH" Tab listing the six interoperability requirements the issue calls out (forward stdin/stdout promptly, preserve newlines, don't wait for EOF, avoid fixed-size blocking reads, keep stderr separate). Cite the exact symptom phrasing the issue uses (imsg rpc timeout) so operators searching for that error find the warning. Note the practical pitfall that pipelines like ssh host imsg | grep ... need stdbuf -oL -eL on every stage to stay safe — line-buffered tools can still hold frames otherwise.

Diff stat: 1 file, +12 / -0. Documentation-only.

Real behavior proof

• Behavior or issue addressed: Sanitized issue evidence — the issue describes that a custom stdio bridge wrapper using a large blocking read(N) produced imsg rpc timeout (chats.list) until the wrapper was changed to forward bytes/lines as soon as they were available. The fix documents this constraint at the spot operators actually look.

• Real environment tested: Local Node 22.x. Probe at /tmp/probe_84330.mjs (a) verifies the <Warning> block was added to docs/channels/imessage.md and lives inside the "Remote Mac over SSH" Tab, (b) checks coverage against the issue's "Expected Documentation" list — all six bullets present (forward stdin/stdout promptly, preserve newlines, don't wait for EOF, avoid fixed-size blocking reads, keep stderr separate), (c) confirms the exact symptom phrasing imsg rpc timeout is cited so operators searching for that error find this section, (d) confirms surrounding sections (Tab intro + Requirements heading) are unchanged, (e) checks <Warning> open/close tags are balanced.

• Exact steps or command run after this patch: node /tmp/probe_84330.mjs

• Evidence after fix:

PASS: <Warning> block added that mentions cliPath wrapper
PASS: warning block lives inside the 'Remote Mac over SSH' Tab
PASS: all 6 required bullets from issue's "Expected Documentation" are covered
PASS: warning cites the exact symptom from the issue ('imsg rpc timeout')
PASS: surrounding sections (Tab intro + Requirements heading) are unchanged
PASS: <Warning> open/close tags balanced (4 pairs)

ALL CASES PASS

• Observed result after fix: Operators following the "Remote Mac over SSH" Tab now see the streaming requirement directly under the wrapper-script example. The Warning calls out the visible symptom (imsg rpc timeout), the structural requirements, and a common pitfall (grep pipelines without stdbuf -oL) that produces the same failure mode.

• What was not tested: No iMessage instance was actually run against a buffering wrapper to reproduce the symptom — this is a documentation-only change to an existing operator-facing manual page. The doc updates the section the issue explicitly suggests in "Suggested Location" (docs/channels/imessage.md near the Remote Mac over SSH wrapper section).

Audit (per CLAUDE rules — all 5 steps)

• Existing-helper check: No code helper introduced — documentation block additive. The <Warning> Mintlify component is the established callout convention used throughout this doc and across the docs site. PASS
• Shared-helper caller check: No code is being modified, so no caller-side contracts exist. PASS
• Broader-fix rival scan: gh pr list --search '84330 in:title,body' and gh pr list --search 'iMessage cliPath wrapper' return no open PRs. Issue timeline shows zero cross-references. PASS
• Recent-merge audit: git log --oneline -5 -- docs/channels/imessage.md shows no recent commits touching this file. PASS
• Prototype-pollution scan: N/A — markdown.

Changed files

• docs/channels/imessage.md (modified, +12/-0)