The iMessage Wrapper Trap Nobody Warned You About
OpenClaw's iMessage integration relies on a companion binary called imsg that communicates with the gateway over long-lived JSON-RPC, exchanging small newline-framed messages on stdin and stdout for the entire lifetime of the channel. It's a clean design — until someone puts a wrapper in front of it.
The problem is subtle. SSH proxies, logging shims, and shell wrappers are common in production deployments, especially when the Mac running iMessage sits on a different network than the OpenClaw gateway. But many of these tools buffer input by default. They wait for EOF before forwarding stdin, or they accumulate data into fixed-size blocks before flushing. For a one-shot command, that's fine. For a persistent JSON-RPC pipe, it's fatal.
The symptoms are insidious: operators see imsg rpc timeout (chats.list) errors or watch the channel restart repeatedly, even though the underlying RPC layer is perfectly healthy. The gateway thinks the connection has stalled. In reality, a wrapper is holding bytes hostage.
The newly documented warning lays out six explicit interoperability requirements that any wrapper or proxy must meet:
- Forward each stdin chunk immediately — never wait for EOF
- Forward each stdout chunk promptly in reverse
- Preserve newline framing for JSON-RPC protocol integrity
- Avoid fixed-size blocking reads like
read(4096),cat | buffer, or shellread - Keep stderr separate from the JSON-RPC stdout stream
- Use
stdbuf -oLon every stage of any filter pipeline
The documentation explicitly calls out a common pattern that looks safe but isn't: piping through grep. A pipeline like ssh host imsg | grep -v '^DEBUG' will stall because grep buffers by default when its output isn't a terminal. The safe form — ssh -T host imsg "$@" — is now the documented baseline.
This is the kind of documentation that prevents a category of support tickets. Operators who hit these timeouts had no way to know the wrapper was the culprit — every diagnostic pointed at the RPC layer, not the transport. Naming the failure mode and listing the requirements upfront saves hours of debugging.
xAI Code Execution Auth Docs Finally Cover All Three Paths
OpenClaw's code_execution tool gives agents the ability to run sandboxed Python remotely through xAI's Responses API. It's one of the more powerful built-in tools — useful for calculations, statistical analysis, and data processing without touching the local filesystem.
Until now, the auth documentation for this tool was narrowly scoped. The credential table implied API-key authentication was the only path, even though OpenClaw has supported xAI OAuth via SuperGrok and X Premium subscriptions for weeks. Operators using OAuth or device-code authentication had to infer that their credentials would work.
The update broadens the authentication table to explicitly list all three methods: OAuth through an eligible subscription, device-code flow for environments where browser-based OAuth can't reach localhost, and the traditional XAI_API_KEY environment variable. It also corrects the documented missing_xai_api_key JSON error example so the message matches what the xAI runtime actually returns. Small details, but documentation that contradicts runtime output erodes trust fast.
Two documentation updates in a single day. The iMessage wrapper warning is the kind of preventive documentation that open-source projects rarely ship until the issue tracker overflows. The xAI auth fix is smaller but signals a maturing posture: documentation should reflect every supported credential path, not just the one that shipped first.