LLM Loop Breaker

Two-layer defense for Openclaw gateway: kills hallucinating LLM streams via entropy analysis, and watchdogs host CPU/RAM/Disk to prevent resource exhaustion.

Security Scan

The package's code and install steps are consistent with its stated purpose (patching fetch to abort low-entropy LLM streams and running a host watchdog), but it is invasive (modifies the gateway binary, starts a background daemon that can kill processes and collects system logs), so review and test before deploying to production.

Purpose & Capability

The name/description (entropy-based stream breaker + host watchdog) match the required binaries (node, python3, bash), the files present (Node.js breaker and Python watchdog), and the install actions. OPENCLAW_APP_DIR is used as the target installation path; nothing requested appears unrelated to the stated purpose.

Instruction Scope

SKILL.md and deploy.sh explicitly instruct the agent to copy files into the Openclaw installation and inject a code block into openclaw.mjs which patches global.fetch and starts a Python daemon. Those instructions are invasive (modify the gateway binary) but are directly tied to the described functionality; they do not reference unrelated secrets or remote endpoints. The watchdog captures local system logs (journalctl, dmesg) into the workspace for incident snapshots — this is expected for forensic snapshots but worth noting as sensitive.

Install Mechanism

No external downloads or unknown URLs: deploy.sh copies local files into $OPENCLAW_APP_DIR and installs psutil via apt-get or pip if needed. The install is deterministic and idempotent as claimed; no archive extraction from untrusted hosts detected.

Credentials

The only required env var is OPENCLAW_APP_DIR (used as an installation root) and the watchdog optionally uses OPENCLAW_WORKSPACE. No unrelated credentials are requested. However the skill writes into the Openclaw installation, uses HOME to place logs (~/.openclaw), creates an agents sessions directory, and collects system logs — these are legitimate for a supervisor but may expose sensitive local/system data, so confirm you’re comfortable with that scope.

Persistence & Privilege

The deploy script injects code into openclaw.mjs (modifies an existing gateway binary) and the injected code will start a background watchdog daemon on gateway startup that can kill gateway child processes based on heuristics and write forensic snapshots. This is consistent with the skill’s purpose but is a high-impact, persistent change: it can cause service disruption if heuristics misfire. The skill is not marked always:true, but it does gain ongoing privileges by modifying the gateway.

Assessment

This skill's code is coherent with its description, but it is invasive: it injects code into your gateway binary and launches a watchdog that can kill processes and collects system logs. Before installing: (1) review the injected code and the full watchdog script (you have a backup step in deploy.sh — keep that backup), (2) run it in a staging environment and exercise the test suites, (3) confirm you accept local log/incident collection (journalctl/dmesg) and the watchdog's kill policies, and (4) ensure the user running the gateway has appropriate permissions (journalctl/dmesg access may require elevated rights). If anything is unclear, ask the author for provenance or run the deployment in an isolated environment first.

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.

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.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

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.