- name
- LLM Stream Guard
- description
- >
- metadata
- openclaw
- emoji
- \F6E1
- homepage
- https://github.com/openclaw/clawhub
- os
- requires
- bins
- env
- install
- name
- n/a
- name
- psutil
- primaryEnv
- OPENCLAW_APP_DIR
- skillKey
- llm-stream-guard
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:
- Accumulates text chunks and measures compressed-vs-raw byte ratio using
zlib deflate (compression ratio = uncompressed / compressed).
- Every 1024 bytes, schedules an entropy check via
process.nextTick. - 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%
- 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.
| Rule | Trigger | Action |
|---|---|---|
| Redline breach | CPU >= 90% OR RAM >= 90% OR Disk >= 90% | Log warning + audit entry |
| Poison pill | Child process CPU > 95% with 0 I/O for 15 s | Kill process tree + incident snapshot |
| Memory leak | RSS monotonically grows > 100 MB over 60 s, CPU > 30% | Kill process tree + incident snapshot |
| Crash loop | Gateway PID changes 3+ times in 120 s | Incident snapshot + 30 s cooldown |
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.shThe script will:
- Verify
python3,psutil, and$OPENCLAW_APP_DIR/openclaw.mjsexist. - Copy runtime files to
$OPENCLAW_APP_DIR/dist/llm_stream_guard/. - Inject bootstrap code into
openclaw.mjs(skipped if already present). - Create a timestamped backup of
openclaw.mjsbefore 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.pyBoth test suites are deterministic and produce exit code 0 on success, 1 on failure.
Files
| File | Purpose |
|---|---|
src/stream-entropy-breaker.cjs | Fetch-patching + stream transform + abort logic |
src/entropy-engine.cjs | Zlib compression ratio calculator + repetition detector |
host-resource-watchdog.py | System resource monitor daemon |
deploy.sh | Deterministic deployment script |
test-entropy-breaker.js | JS test suite (16 tests) |
test-watchdog.py | Python test suite (14 tests) |
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.