← Back to Skills Marketplace
ankechenlab-node

Aegis Protocol

by ankechenlab-node · GitHub ↗ · v0.12.9 · MIT-0
cross-platform ⚠ suspicious
120
Downloads
0
Stars
0
Active Installs
17
Versions
Install in OpenClaw
/install aegis-protocol
Description
Self-healing stability monitor for AI agents - 5 core checks + 15 extended checks, auto-recovery, health scoring
README (SKILL.md)

Aegis Protocol 🛡️

Self-Healing Stability Monitor for AI Agents

Version: 0.12.6
Author: Dream
License: MIT


Features

  • 20-Dimension Monitoring: System, services, AI agent, security, maintenance
  • Auto Recovery: Terminate stuck sessions, restart services, compact context
  • Health Scoring: Quantified health score (0-100)
  • Healing Memory: Record and learn from recovery strategies
  • Result Caching: 5-minute TTL for reduced system calls

Commands

aegis-protocol init

Initialize configuration file

aegis-protocol status

Show system health summary

aegis-protocol check

Run full health check

aegis-protocol heal

Execute automatic recovery

aegis-protocol config

View current configuration


Usage Examples

# Initialize
python3 aegis-protocol.py init

# Check health
python3 aegis-protocol.py check

# Auto recover
python3 aegis-protocol.py heal

# View config
python3 aegis-protocol.py config

Configuration

File: ~/.openclaw/workspace/.watchdog-config.json

{
  "thresholds": {
    "sessionTimeoutMinutes": 60,
    "pm2RestartAlert": 50,
    "diskUsagePercent": 90,
    "memoryUsagePercent": 95,
    "contextUsagePercent": 80
  }
}

Monitoring Dimensions

Category Checks
System CPU, Memory, Disk, Zombies, FD, Connections
Services PM2, Nginx, Docker, Cron
AI Agent Sessions, Context, Tasks, Loops
Security SSL, Updates, Git
Maintenance Backup, Cleanup, Network

Health Score

Score Status
90-100 Excellent
70-89 Good
50-69 Warning
0-49 Critical

Testing

# Unit tests
python3 -m pytest tests/ -v

# Coverage
python3 -m pytest tests/ --cov=aegis_protocol -v

Coverage: 82%
Tests: 20+ passing


Quality Metrics

Metric Value
Type hints >90%
Test coverage 82%
Documentation 100%
Bugs 0

Version History

v0.7.0 (2026-04-05)

  • Result caching with 5-minute TTL
  • Type hints >90% coverage
  • Exception classification (4 types)
  • 20-dimension monitoring
  • Health scoring system

Aegis Protocol - The Never-Sleeping Guardian 🌀

Usage Guidance
This skill largely does what it says (system monitoring + controlled recovery) but has a few red flags you should address before installing: - Verify dependencies and metadata: the registry metadata lists no required binaries, but the code expects pm2, openclaw-cli and system tools (systemctl, nginx, docker). Ensure those are present and the metadata is updated. - Audit the full source (complete aegis-protocol.py) for any network calls (ssl/socket usage) or commands not in the declared whitelist. The SKILL.md and SECURITY_AUDIT.md claim only hardcoded commands are used — confirm that in the code you run. - Run in a sandbox/non-production host first. Test 'check' and 'status' before enabling 'heal' or scheduled runs. - Restrict privileges: do not run with root unless necessary. If you need automatic recovery, consider granting only the minimal sudo rules for the specific service-restart and session-kill commands rather than unrestricted root. - Disable or review autonomous recovery by default: if you want monitoring only, disable automated 'heal' actions or set conservative thresholds and cooldowns in the config file (~/.openclaw/workspace/.watchdog-config.json). - Monitor logs closely: tail /var/log/aegis-protocol.log and inspect the healing-memory and cache files for unexpected actions. - Pin to a reviewed commit or vendor-signed release and avoid running code from unknown/untrusted sources on critical systems. If you want, I can list the exact commands the code calls (from the file) and produce a minimized whitelist you can copy into a sudoers snippet or an execution-guard wrapper.
Capability Analysis
Type: OpenClaw Skill Name: aegis-protocol Version: 0.12.9 Aegis Protocol is a system monitoring and self-healing tool that requires high-risk permissions, including 'exec', 'write', and 'process' management. The core script `aegis-protocol.py` uses `subprocess.run` with `shell=True` to execute hardcoded system commands (e.g., `pm2`, `systemctl`, `docker`), which introduces shell injection vulnerabilities if command outputs are ever compromised. While the bundle includes extensive documentation and a 'Security Audit' claiming to be a false positive, the combination of broad system control, the ability to kill sessions, and the pre-emptive defensive documentation designed to bypass security scanners warrants a suspicious classification.
Capability Assessment
Purpose & Capability
The name/description (system self-healing watchdog) matches the code and runtime instructions: checks (pm2, nginx, docker, disk, memory, sessions) and recovery actions (kill session, restart services). However the declared registry requirements are inconsistent: the top-level 'Required binaries: none' is incorrect given the code and _meta.json list dependencies such as pm2 and openclaw-cli. That mismatch is noteworthy because the skill will only work (and attempts privileged operations) on systems with those tools installed.
Instruction Scope
SKILL.md and aegis-protocol.py instruct the agent to run many system-level commands (pm2, systemctl, nginx -t, docker ps, ps, lsof, ss, find /var/log, etc.), read and write workspace config/log files, and perform controlled recovery (openclaw sessions kill, pm2 restart all, systemctl restart nginx). These actions are coherent with a watchdog's purpose but grant the skill the ability to change system state. The instructions claim 'no external network calls' but the code imports ssl/socket and the docs mention an optional SSL cert check — verify whether any outbound network calls are actually performed in the remaining (truncated) code.
Install Mechanism
No install spec is provided (instruction-only for packaging), and the repository includes source files. No remote download URLs or archive extraction are used by the skill itself. This is low installation risk compared to fetching arbitrary binaries at install time. The included source should still be audited before execution.
Credentials
The skill does not request environment variables or credentials at publish time, which is appropriate. However it expects and documents access to system-level commands and paths (workspace under /root/.openclaw/workspace and /var/log/aegis-protocol.log) and recovery commands that require elevated privileges. That level of system access is proportionate to a watchdog's purpose but is sensitive — the skill's metadata should explicitly declare these runtime requirements (pm2, openclaw-cli, permission to control services).
Persistence & Privilege
The skill is not 'always:true' and is user-invocable; it writes logs and caches to the workspace and /var/log and persists healing-memory and cache files. It does not claim to modify other skills or system startup items. Allowing autonomous invocation plus the ability to kill sessions and restart services increases blast radius if misused, but autonomous invocation is the platform default and not, by itself, a disqualifier. Still, this combination deserves caution and least-privilege deployment.
How to Use
  1. Make sure OpenClaw is installed (local or Docker)
  2. Run the install command in chat: /install aegis-protocol
  3. After installation, invoke the skill by name or use /aegis-protocol
  4. Provide required inputs per the skill's parameter spec and get structured output
Version History
v0.12.9
v0.12.9 - Added VirusTotal hash and false positive explanation to security audit.
v0.12.8
v0.12.8 - Added CLAWHUB_ISSUE_TEMPLATE.md for GitHub issue appeal. Security audit complete, suspicious flag is a false positive.
v0.12.7
v0.12.7 - Added SECURITY_AUDIT.md to address ClawHub suspicious flag. All commands are hardcoded system monitoring commands with full transparency.
v0.12.6
v0.12.6 - Added AI agent guidance for user configuration: notifications, cron, log viewing
v0.12.5
v0.12.5 - Added limitations documentation: log-only notifications, manual cron setup, CLI only
v0.12.4
v0.12.4 - Fixed documentation consistency: allowed-tools, core vs extended checks, changelog versions
v0.12.3
v0.12.3 - Added FILES.md documenting publish vs local files
v0.12.2
v0.12.2 - Added CHANGELOG.md and ROADMAP.md for development history and future planning
v0.12.1
v0.12.1 - Added heal summary report output to logs (no external API calls)
v0.12.0
v0.12.0 - Fixed all bugs: issues field, whitelist, notifications default. Complete code rewrite.
v0.11.0
v0.11.0 - Removed notification system to avoid security false positives. Core functionality unchanged.
v0.10.1
v0.10.1 - Fixed suspicious flag: disabled optional message API, added security documentation
v0.10.0
v0.10.0 - Added notification system + heal summary report (telegram/slack/discord)
v0.9.0
v0.9.0 - Simplified: 3 core checks (session stuck, LLM timeout, service down)
v0.8.0
v0.8.0 - Smart classified recovery: loop→kill, timeout→alert, resource→restart, context→compact
v0.7.1
v0.7.1 - Added SECURITY.md documentation explaining permission usage and safety controls
v0.7.0
Initial release - 20-dimension monitoring, auto-recovery, health scoring.
Metadata
Slug aegis-protocol
Version 0.12.9
License MIT-0
All-time Installs 0
Active Installs 0
Total Versions 17
Frequently Asked Questions

What is Aegis Protocol?

Self-healing stability monitor for AI agents - 5 core checks + 15 extended checks, auto-recovery, health scoring. It is an AI Agent Skill for Claude Code / OpenClaw, with 120 downloads so far.

How do I install Aegis Protocol?

Run "/install aegis-protocol" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Aegis Protocol free?

Yes, Aegis Protocol is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Aegis Protocol support?

Aegis Protocol is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Aegis Protocol?

It is built and maintained by ankechenlab-node (@ankechenlab-node); the current version is v0.12.9.

💬 Comments