What's Fixed

🔧 Critical Bug Fixes

• Level 2→3 chain was disconnected: watchdog never actually called emergency-recovery — now fixed
• Discord webhook env var missing: .env was never created during install, so Level 4 alerts never fired
• Installer only set up healthcheck: full 4-tier chain was never wired together

🆕 Changes

• gateway-watchdog.sh v4.1: auto-escalates to Level 3 after 30min continuous failure
• emergency-recovery-v2.sh: graceful .env loading + webhook fallback
• install.sh: complete rewrite with interactive setup + chain verification
• install-linux.sh: systemd-based full chain setup
• .env.example: all variables documented
• README.md: accurate architecture diagram

⚠️ Breaking Changes

• install.sh now sets up the full 4-tier chain (not just Level 2)
• LaunchAgent uses StartInterval only (no KeepAlive)

Install / Upgrade

curl -sSL https://raw.githubusercontent.com/Ramsbaby/openclaw-self-healing/main/install.sh | bash

What is OpenClaw Self-Healing?

AI-powered 4-tier autonomous recovery system for OpenClaw Gateway.

• Level 1: Process restart
• Level 2: Health check (HTTP + 3 retries)
• Level 3: Claude Code emergency doctor (AI diagnosis)
• Level 4: Discord notification (human escalation)

Release Notes — v3.0.0

Release Date: 2026-02-18
Type: Major Release
Compatibility: macOS 12+, Linux (beta)

🎉 Highlights

v3.0.0 introduces Self-Optimization — the system can now analyze its own operation logs, detect recurring failure patterns, and propose improvements to your AGENTS.md configuration. The AI doesn't just heal crashes; it learns to prevent them.

This release also includes a major README overhaul for clarity and honesty, plus official Telegram notification support (contributed by the community 🙏).

✨ What's New

Self-Optimization Engine (Self-Evolving)

The system now performs a weekly self-review:

1. Log Analysis — Scans the past 7 days of recovery logs
2. Pattern Detection — Identifies recurring failure signatures (e.g., config corruption, API timeouts)
3. Improvement Proposals — Generates concrete suggestions for AGENTS.md
4. User Approval — All suggestions require explicit approval before any changes are applied

This feature absorbs the previously separate "self-evolving" functionality into the core system.

How to use:

# Manually trigger a self-optimization review
bash ~/openclaw/scripts/self-optimize.sh --dry-run

# View pending suggestions
cat ~/openclaw/memory/optimization-proposals.md

Telegram Notifications (PR #5 by @AbhiWisdom)

Configure Telegram as an alternative (or additional) alert channel:

# Add to ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

Both Discord and Telegram can be active simultaneously. If both are configured, alerts go to both channels.

📋 Full Changelog

Added

• Self-Optimization: AGENTS.md 자동 분석 및 개선안 제안
• 주 1회 로그 분석 → 패턴 감지 → 개선안 생성
• 사용자 승인 필수 워크플로우

Changed

• README 전면 개선: 496줄 → 250줄 이내
• 과대광고 배지 제거 (9.9/10, 99% recovery)
• mermaid → 텍스트 기반 다이어그램

Fixed

• Telegram notification support (PR #5 by @AbhiWisdom)

🚀 Installation & Upgrade

Fresh Install

curl -fsSL https://raw.githubusercontent.com/ramsbaby/openclaw-self-healing/main/install.sh | bash

Upgrade from v2.x

cd ~/path/to/openclaw-self-healing

# Pull latest
git pull origin main

# Re-run installer (safe — won't overwrite .env)
bash install.sh --upgrade

The installer detects existing installations and performs a non-destructive upgrade.

🔄 Migration Guide: v2.x → v3.0

What Changes

Migration Steps

1. Backup your .env:

   cp ~/.openclaw/.env ~/.openclaw/.env.v2-backup

2. Pull v3.0:

   cd ~/openclaw-self-healing
   git pull origin main

3. Run upgrade:

   bash install.sh --upgrade

4. (Optional) Add Telegram:

   echo "TELEGRAM_BOT_TOKEN=xxx" >> ~/.openclaw/.env
   echo "TELEGRAM_CHAT_ID=yyy" >> ~/.openclaw/.env

5. Verify:

   # Check all LaunchAgents are loaded
   launchctl list | grep openclaw
   
   # Test health check
   curl http://localhost:18789/

No Breaking Changes

v3.0 is fully backward compatible with v2.x configurations.

• All existing .env variables continue to work
• LaunchAgent plist files are unchanged
• Script interfaces are unchanged
• No database migrations required

⚠️ Known Issues

• Self-optimization cron requires CLAUDE_API_KEY to be set (same as emergency recovery)
• Linux systemd support remains in beta; some features may not work identically to macOS
• Prometheus metrics export (announced in v2.1 roadmap) is delayed to v3.1

🙏 Credits

• @AbhiWisdom — Telegram notification support (PR #5)
• Everyone who reported issues, starred the repo, and gave feedback

📎 Resources

• Full Changelog
• Quick Start Guide
• Troubleshooting
• Contributing Guide
• GitHub Discussions

What's New

🐧 Linux Support (Full)

• One-click installer: curl -sSL .../install-linux.sh | bash
• User-level systemd: No sudo required
• Distro detection: Ubuntu, Debian, RHEL/CentOS, Arch, Raspberry Pi
• 4 systemd unit files: gateway, healthcheck (service+timer), emergency recovery

📋 Community

• 4 Good First Issues: Docker, Grafana, Multi-channel alerts, BATS tests
• Star History chart in README
• Comprehensive Linux Setup Guide

🔧 Fixes

• gateway.service: Fixed non-existent --foreground flag
• emergency-recovery.sh: Linux-aware install hints
• shellcheck warnings resolved

Breaking Changes

None. Fully backward compatible with macOS.

Full changelog: CHANGELOG.md

🐛 Hotfix Release

Fixed

• Discord webhook HTTP 404 error: Removed DISCORD_WEBHOOK_URL dependency
  • Alert messages now output to stdout for cron delivery system
  • Eliminates configuration complexity (no webhook setup required)
  • Backwards compatible: works with OpenClaw cron delivery settings
  • Tested with actual emergency recovery failure scenario ✅

Changed

• Simplified alert delivery mechanism: stdout → cron delivery → Discord channel
• Removed unused environment variable loading code

Verification

All tests passed:

• ✅ Discord webhook removed
• ✅ Stdout delivery working
• ✅ No HTTP errors
• ✅ Duplicate detection working

Upgrade Instructions

cd ~/openclaw/skills/openclaw-self-healing
git pull
git checkout v2.0.2

Or fresh install:

curl -fsSL https://raw.githubusercontent.com/Ramsbaby/openclaw-self-healing/main/install.sh | bash

Full Changelog: v2.0.1...v2.0.2

v2.0.1 — Critical Bug Fixes

This patch release fixes a critical logic bug in the reasoning log extraction feature introduced in v2.0.0.

🐛 Fixed

Critical: Reasoning Log Extraction

• Issue: reasoning_file parameter was declared but never used in extract_learning() function
• Impact: Claude's reasoning process (Decision Making, Lessons Learned) was not being captured in recovery-learnings.md
• Fix: Implemented proper extraction logic with graceful fallback when reasoning log is missing
• Verification: Unit tested with mock recovery scenarios

Version Consistency

• Unified script header version from v2.0 to v2.0.0 across all files
• All components now report consistent version numbers

Environment Variable Naming

• Fixed inconsistency: DISCORD_WEBHOOK vs DISCORD_WEBHOOK_URL
• Now consistently uses DISCORD_WEBHOOK_URL throughout the codebase

ShellCheck Warnings

• Fixed SC2162: Added -r flag to read command in metrics-dashboard.sh
• Improved code quality compliance

✨ Improved

• Edge case handling: Graceful fallback message when reasoning log file is missing
• Code quality: Applied ShellCheck recommendations for better maintainability

📊 Testing

All patches verified through 3-layer validation:

1. ✅ Syntax & ShellCheck (no critical warnings)
2. ✅ Version & logic consistency (all files match v2.0.1)
3. ✅ Logic flow & edge cases (unit tested with mock data)

📚 What's Next

• v3.0.0 candidates:
  • Multi-Gateway support
  • Windows/WSL2 support
  • Web-based metrics UI

Full Changelog: v2.0.0...v2.0.1

Upgrade:

cd ~/openclaw/skills/openclaw-self-healing
git pull origin main

First time install:

curl -sSL https://raw.githubusercontent.com/Ramsbaby/openclaw-self-healing/main/install.sh | bash

🚨 CRITICAL HOTFIX - Update Immediately

This hotfix removes a fatal flaw in v1.1.0 that caused Gateway to stop restarting after 2 crashes within 10 seconds.

If you deployed v1.1.0, you MUST upgrade to v1.1.1 now.

🐛 The Bug

Problem

<key>ThrottleInterval</key>
<integer>10</integer>

Impact: Gateway stops restarting after 2 crashes within 10 seconds (launchd crash loop protection).

Real-World Scenario

Crash 1 (00:00:00) → Restart (00:00:02) ✅
Crash 2 (00:00:05) → NO RESTART (throttled) ❌ 💀
Crash 3 (00:00:13) → Restart (throttle expired) ✅

This breaks self-healing during rapid failures!

✅ The Fix

Remove ThrottleInterval entirely.

Why It's Safe

• KeepAlive still protects against infinite crash loops
• Watchdog monitors Gateway health every 60 seconds
• Guardian watches Watchdog every 3 minutes
• No risk of uncontrolled restarts

📊 Test Results

Before (v1.1.0 with ThrottleInterval)

Stress Test: 2/3 success (66%)
Crash 1: ✅ Recovered (4s)
Crash 2: ❌ FAILED (throttled, no restart)
Crash 3: ✅ Recovered (delayed)

After (v1.1.1 without ThrottleInterval)

Stress Test: 3/3 success (100%)
Crash 1: ✅ Recovered (4s)
Crash 2: ✅ Recovered (6s)
Crash 3: ✅ Recovered (8s)
Average: 6 seconds

Final Score: 10.0 / 10.0 (perfect)

🚀 Upgrade Instructions

Option 1: Download New plist

curl -sSL https://raw.githubusercontent.com/Ramsbaby/openclaw-self-healing/v1.1.1/launchagent/ai.openclaw.gateway.plist.example \
  -o ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# Edit with your API keys
nano ~/Library/LaunchAgents/ai.openclaw.gateway.plist

launchctl bootout gui/$(id -u)/ai.openclaw.gateway
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Option 2: Manual Edit

# Edit Gateway plist
nano ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# Remove these lines:
# <key>ThrottleInterval</key>
# <integer>10</integer>

# Reload
launchctl bootout gui/$(id -u)/ai.openclaw.gateway
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Verification

# Stress test (should all succeed now)
for i in {1..3}; do
  kill -9 $(pgrep -f openclaw-gateway)
  sleep 8
  curl -s http://localhost:18789/health && echo "✓ Recovery $i"
done

📈 What's Changed

Modified:

• launchagent/ai.openclaw.gateway.plist → .plist.example (security)
• Removed ThrottleInterval from Gateway configuration

Full Changelog: v1.1.0...v1.1.1

🙏 Apologies

This bug was discovered during stress testing after v1.1.0 release. We apologize for not catching this earlier.

Lesson learned: Always test rapid consecutive failures, not just single crashes.

📚 Resources

• Stress Test Script
• Report Issues

Upgrade now. Your Gateway deserves 100% recovery, not 66%. 🚀

Discovered & Fixed: 2026-02-07 20:21
Tested: 3/3 consecutive crashes (100% success)

GitHub Actions CI Fix

ShellCheck SC2317 (unreachable code) warning suppressed for trap cleanup function.

# shellcheck disable=SC2329,SC2317
cleanup() { ... }
trap cleanup EXIT INT TERM

These warnings are false positives - the cleanup function IS called via trap.

ShellCheck 100% Clean

• Fixed variable quoting ($exit_code, $ALERT_TMP)
• Suppressed SC2329 false positive (trap indirect call)

shellcheck scripts/*.sh  # ✅ No warnings

🔴 Critical Fixes

1. File Creation Order (Breaking Bug)

Before: Tried to create SESSION_LOG before directory existed → crash on fresh install
After: Directory created first, then files

2. Lock File Security

Before: /tmp/openclaw-emergency-recovery.lock (any user can create → DoS)
After: $LOG_DIR/.emergency-recovery.lock (user-only directory)

3. Completion Detection False Positives

Before: grep -qE "done|finished|completed" → triggers on "done checking"
After: More specific patterns like "recovery completed", "gateway restored"

4. Session Output Loss

Before: Only captured at end → missed intermediate output
After: Captures during each poll cycle

Upgrade

curl -sSL https://raw.githubusercontent.com/Ramsbaby/openclaw-self-healing/main/install.sh | bash

🐛 Bug Fixes

Dead Code Removed

• Unused log_incident() function was defined but never called
• Cleaned up for code hygiene

Performance: Smart Completion Detection

Before: Wait full 30 minutes regardless of Claude's progress
After: Poll every 30s, detect completion via:

• Output patterns (✅, completed, finished)
• Idle detection (3 min no output = done)

Result: Typical recovery now takes 5-10 minutes instead of 30.

Security Hardening

• Temp files now use mktemp (no predictable paths)
• Session logs get chmod 600 immediately

Full Changelog

See CHANGELOG.md