---
name: openclaw-audit
description: Audit OpenClaw runtime logs, session transcripts, tool failures, and correlate errors with recent git commits across infrapuzzle, mop-skills, and knowledge-wiki. Use when performing system health audits, investigating tool failures, or running the weekly IT Guy self-audit.
---

# 🩺 OpenClaw System & Log Self-Audit (`openclaw-audit`)

Comprehensive system diagnostic and correlation engine designed for **IT Guy** (`itguy`). It analyzes runtime container stdout logs, session transcripts, and tool execution failures across all agents, correlates errors with recent Git commits across the 3 core repositories, and files structured audit reports and actionable task queue entries into the Knowledge Wiki.

## 🎯 When to Use
- **Weekly Scheduled Audit**: Triggered automatically via OpenClaw Cron (`itguy-weekly-health-audit`) every Sunday at 03:00 Europe/Berlin.
- **On-Demand Diagnostics**: Whenever the user asks: *"Prüfe die Logs von OpenClaw"*, *"Gibt es Tool-Fehler?"*, *"Audit durchführen"*, *"System-Health prüfen"*.
- **Post-Deployment Validation**: After making configuration, skill, or manifest changes to verify whether errors appeared.

---

## 🗂️ The Three Core Repositories Architecture
The audit correlates runtime behavior with recent git commits across three foundational repositories:

1. **`infrapuzzle`** (`/home/node/infrapuzzle/infrapuzzle` or `/home/node/.openclaw/repos/infrapuzzle`):
   - Scope: Cluster infrastructure, Kubespray bootstrap, K8s manifests, Terraform DNS, ESPHome IoT, ADRs.
2. **`mop-skills`** (`/home/node/mop-skills/mop-skills`):
   - Scope: Custom Python skills, CLI utilities, and MCP server bridges.
3. **`knowledge-wiki`** (`/home/node/.openclaw/wiki/main`):
   - Scope: Agents-as-code (`agents/*.md`), active task queue (`tasks/antigravity.md`), family knowledge vault, and audit archives (`operations/audits/`).

---

## 🛠️ CLI Operations Reference

### 1. Standard Audit (Inspection Only)
```bash
uv run /home/node/mop-skills/mop-skills/skills/openclaw-audit/scripts/audit_openclaw.py --since 7d
```
Fetches container logs from the last 7 days, parses session transcripts across all agents, summarizes recent commits from all 3 git repos, and outputs a formatted diagnostic markdown report to stdout.

### 2. Full Audit with Wiki Archival & Task Filing
```bash
uv run /home/node/mop-skills/mop-skills/skills/openclaw-audit/scripts/audit_openclaw.py \
  --since 7d \
  --write-report \
  --add-task \
  --git-push
```
- **`--write-report`**: Writes the detailed diagnostic report to `/home/node/.openclaw/wiki/main/operations/audits/YYYY-Wxx.md`.
- **`--add-task`**: Appends any newly detected, deduplicated high/critical issues to `/home/node/.openclaw/wiki/main/tasks/antigravity.md` under `## 📥 Pending Tasks`.
- **`--git-push`**: Commits and pushes the modified wiki pages directly to `git.moritzgraf.de/moritz/knowledge-wiki.git`.

### 3. Machine-Readable JSON Output
```bash
uv run /home/node/mop-skills/mop-skills/skills/openclaw-audit/scripts/audit_openclaw.py --since 24h --json
```
Returns a structured JSON payload containing `status`, `recent_commits`, `error_clusters`, `session_tool_failures`, and `affected_agents`.

---

## 🤖 Protocol for IT Guy Agent (`itguy`)

When executing the weekly audit turn:
1. Run the audit script:
   ```bash
   uv run /home/node/mop-skills/mop-skills/skills/openclaw-audit/scripts/audit_openclaw.py --since 7d --write-report --add-task --git-push
   ```
2. Review the aggregated output:
   - Check if any new issues were added to `tasks/antigravity.md`.
   - Correlate any error spikes with commits in `infrapuzzle` or `mop-skills`.
3. Delivery Decision:
   - **If issues were found and tasks added**: Send a concise summary of findings, affected agents/tools, and links to the wiki task queue directly into Telegram Topic `#IT Guy` (thread `119`).
   - **If zero issues / all healthy**: Respond with **`NO_REPLY`** to maintain intentional silence (no Telegram notification spam).