2026 OpenClaw stdio buffering, MCP JSON-RPC stalls, and pipe backpressure on a rented ProxyMac Mac mini

OpenClaw on a ProxyMac Mac mini in Hong Kong, Japan, Korea, Singapore, or the United States often registers MCP servers over stdio: the gateway spawns a child process, speaks JSON-RPC on stdin/stdout, and expects each message to arrive promptly. The failure signature is infuriatingly quiet: first tool call works, then the child stops emitting even though top shows CPU idling. Nine times out of ten the culprit is not “bad models”—it is stdio buffering plus pipe backpressure: the child switches to fully block-buffered mode because it no longer sees a TTY, so partial responses sit in libc until a buffer fills; meanwhile the parent may block on read() waiting for a delimiter that never arrives, or the child blocks on write() because the parent has not drained the pipe. This guide explains the architecture, contrasts line vs block buffering with a symptom matrix, compares PTY wrappers vs raw pipes under launchd, lists mitigations for Python (PYTHONUNBUFFERED=1, python -u), POSIX filters (stdbuf -oL), and Node streams (keep stdout in flowing mode), then gives a five-step triage that plugs into MCP setup, gateway restart, deployment troubleshooting, and ulimits when the issue is actually descriptor starvation masquerading as “hangs.”

stdio MCP architecture on macOS (what must stay true)

Think of three cooperating processes: (A) the OpenClaw gateway, (B) the MCP server binary or script, (C) optional helper filters (jq, language runtimes). Any participant that blocks on write while another waits on read for the same circular dependency creates a deadlock. Stdio transports also inherit stderr discipline: chatty libraries that spew progress bars to stderr can fill kernel pipe buffers if nobody consumes them.

• One JSON message per flush expectation is unrealistic—libc does not know JSON boundaries.
• Large responses need streaming readers; if the gateway buffers entire payloads in RAM, you will feel “stalls” unrelated to MCP semantics.
• launchd does not source your interactive shell rcfiles—environment parity is manual; see upgrade/rollback patterns for ordered restarts after env changes.

Line buffering vs block buffering (why Terminal “works”)

Many CLIs use line buffering when isatty(stdout) is true, and block buffering (often multiples of 4–8 KiB) when stdout is a pipe. Under a headless LaunchAgent, your MCP server suddenly becomes a pipe writer—so logs that looked “live” in Terminal batch until the buffer fills. That delay shows up as “the model paused” even though the LLM finished seconds ago.

Hung MCP symptom matrix

Signal	More likely than MCP bugs	Prove / disprove	Next link
First RPC OK, second stalls forever	Block-buffered stdout	Run same binary under script -q /dev/null PTY smoke test	This article
CPU pegged, RAM flat	Tight spin reading empty fd	Sample with sample pid 5 -file /tmp/st.txt	Troubleshooting
Too many open files	Ulimits, MCP fan-out	launchctl limit maxfiles vs process soft limit	Ulimits
Intermittent after log rotation	SIGHUP handling / reopened fds	Correlate timestamps with newsyslog	Logging

PTY wrappers vs raw pipes under LaunchAgents

Some teams wrap MCP servers with script, unbuffer, or custom PTY parents so children believe they are interactive. Trade-offs: PTYs add CPU and copying overhead but remove a class of buffering surprises. Raw pipes stay cheaper but demand disciplined flushing in the child or stdbuf shims. Choose consciously—mixing styles across servers confuses on-call engineers.

Toolchain mitigations (copy into LaunchAgent EnvironmentVariables)

Python: export PYTHONUNBUFFERED=1 or invoke python3 -u; for packaged CLIs, prefer an entrypoint that calls sys.stdout.reconfigure(line_buffering=True) on supported versions. Node: ensure stdout is consumed in flowing mode—paused streams are a common foot-gun when piping between child processes. Go / Rust: flush explicitly after each JSON-RPC frame if you control the source. Shell filters: remember grep --line-buffered when tailing through pipes in automation.

<key>EnvironmentVariables</key> <dict> <key>PYTHONUNBUFFERED</key> <string>1</string> <key>NODE_OPTIONS</key> <string>--max-old-space-size=4096</string> </dict>

Five-step stdio triage before you rewrite the agent

1. Reproduce under ssh with the same plist ProgramArguments pasted into an interactive shell—if it suddenly works, you have an env/TTY delta.
2. Strace-equivalent on macOS: use sudo fs_usage -w -f filesys | grep mcp briefly to see stalled writes (use judiciously in prod).
3. Split stderr to a rotated file so debug spam cannot contend with JSON-RPC on stdout.
4. Soak test with synthetic large payloads after enabling mitigations.
5. Decide transport: if stdio remains fragile, plan HTTP MCP per the setup guide.

FAQ

Does increasing pipe buffer sysctl fix this? Treat that as a last resort—root cause is usually unpaired reader/writer cadence, not buffer size alone.

Should MCP servers log to stdout? Reserve stdout for JSON-RPC only; push human logs to stderr or structured files.

Does Apple Silicon change buffering? No—M4 makes you faster at hitting the bug, not immune to libc defaults.

Why ProxyMac Mac mini is the right place to harden stdio MCP

Apple Silicon M4 minis in HK / JP / KR / SG / US give you always-on metal where you can replay the same stdio graphs nightly, attach regional capacity next to the SaaS APIs you call, and keep help links beside your LaunchAgent repo. When humans must approve TCC prompts, fall back to VNC; when networking injects hesitation, read IPv6 Happy Eyeballs SSH from the same release train.