moritz/infrapuzzle
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(openclaw): persist operational invariants in AGENTS.md and add openclaw-ops skill runbook

Browse Source
This commit is contained in:
Moritz Graf
2026-10-09 07:54:20 +02:00
parent aeea7a8fea
commit 36e0887c73
2 changed files with 199 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
k8s/openclaw/AGENTS.md
+24
View File
@@ -88,6 +88,30 @@ OpenClaw connects to three foundational Git repositories:
> [!IMPORTANT]
> **Mandatory Bug & Incident Documentation**: Whenever a bug, outage, schema error, or operational regression is fixed in OpenClaw, **always document the incident in [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** with symptom, root cause, resolution, and how to avoid recurrence.
### 🛡️ Operational & Diagnostic Invariants (Learned Guidelines)
Whenever troubleshooting or maintaining OpenClaw, agents MUST adhere to these rules:
1. **Verify Before Declaring Dead (Turn In-Flight Diagnostics)**:
- When a user reports that a Telegram topic is "not answering" or "silent", **NEVER assume the container or gateway has crashed**.
- Always inspect live pod logs (`kubectl logs openclaw-0 -n openclaw -c openclaw --tail=100`) and the agent's SQLite database (`session_nodes` and `transcript_events`) first.
- Check whether a turn is currently executing: multi-turn tool loops or inline safeguard compaction (`compact:start`) can introduce multi-minute turn latency without any pod restart.
2. **Datastore Ground-Truth for Maintenance**:
- High-level CLI summaries (`openclaw sessions --all-agents --json`) report `totalTokens: null` (`totalTokensFresh: false`) for stale sessions or after restarts.
- Automated health checks and compaction scripts MUST query the SQLite database directly (`transcript_events` event count and byte size), triggering compaction when `bytes >= 300KB` or `events >= 40`, regardless of cached token values.
3. **Compaction User Visibility**:
- Always ensure `agents.defaults.compaction.notifyUser: true` remains set in OpenClaw configuration. Live inline compactions must send visible status feedback (`🧹 Compacting context...`) to avoid perceived bot stalls.
4. **In-Pod Container Restart Self-Healing**:
- Critical database unlocking, lockfile cleanup, and state recovery MUST run via runtime preflight (`NODE_OPTIONS="--import=..."`) or application startup hooks.
- Never place critical self-healing logic exclusively in `initContainers`, as Kubelet container restarts inside an existing Pod completely bypass `initContainers`.
5. **Rotational Storage (HDD) Page-Cache Pre-Warming**:
- Host `haumdaucher` uses rotational mechanical disks (`/dev/sda2`, `rotational: 1`).
- Whenever the pod or container restarts, SQLite databases MUST be sequentially streamed to `/dev/null` (`cat ... > /dev/null`) to pre-warm the Linux page cache, avoiding single-threaded event loop starvation on cold seeks.
For known issues, resolved bugs, and specific failure playbooks, consult [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
### 1. Verify Deployment Health