LLM Stream Guard

Two-layer runtime defense that protects the Openclaw gateway against hallucinating LLM streams and host resource exhaustion.

When to activate

Activate this skill once per fresh gateway deployment or whenever the gateway binary (openclaw.mjs) is rebuilt / updated.

What it does

Layer 1 -- Stream Entropy Breaker (Node.js)

Patches global.fetch to intercept every LLM streaming response (text/event-stream, application/x-ndjson, application/stream+json).

For each active stream it:

1. Accumulates text chunks and measures compressed-vs-raw byte ratio using zlib deflate (compression ratio = uncompressed / compressed).
2. Every 1024 bytes, schedules an entropy check via process.nextTick.
3. Once 4000+ bytes have been received, evaluates kill conditions:
   • Hard kill: compression ratio > 10.0
   • Soft kill: compression ratio > 6.0 AND single-character dominance > 50%
4. On kill: fires AbortController.abort() with reason HALLUCINATION_LOOP_DETECTED_BY_ENTROPY_BREAKER, severing the stream.

Bounded memory: accumulated text is truncated to the last 4096 characters when it exceeds 8192. A 30-second registry cleanup removes stale streams.

Layer 2 -- Host Resource Watchdog (Python)

Runs as a separate daemon outside the gateway process. Polls every 2 seconds via psutil.

Incident snapshots capture journalctl and dmesg excerpts into ~/.openclaw/workspace/memory/core/incidents/.

Deployment

Run the deterministic deploy script. It is safe to run multiple times (idempotent).

export OPENCLAW_APP_DIR=/app          # path to openclaw installation root
bash deploy.sh

The script will:

1. Verify python3, psutil, and $OPENCLAW_APP_DIR/openclaw.mjs exist.
2. Copy runtime files to $OPENCLAW_APP_DIR/dist/llm_stream_guard/.
3. Inject bootstrap code into openclaw.mjs (skipped if already present).
4. Create a timestamped backup of openclaw.mjs before any modification.

After deployment, restart the Openclaw gateway to activate.

Verify

# Node.js layer tests (no network, no side effects)
node test-entropy-breaker.js

# Python layer tests (mocked psutil, no real process interaction)
python3 test-watchdog.py

Both test suites are deterministic and produce exit code 0 on success, 1 on failure.

Files

Uninstall

Remove the injected block from openclaw.mjs (between the [LLM_STREAM_GUARD_START] and [LLM_STREAM_GUARD_END] markers), delete $OPENCLAW_APP_DIR/dist/llm_stream_guard/, and kill any running host-resource-watchdog.py process.