OpenClaw Agent Guide (Operator-Managed)

This document provides a technical reference for AI agents managing the OpenClaw deployment in this repository.

🏗️ Architecture & Configuration Lifecycle

The deployment has been migrated to the OpenClaw Operator framework.

1. Persistent Storage & State Protection

Storage Claim: Uses the existing PVC openclaw-data (openebs-hostpath).
Zero-Drift Merge: Configured with mergeMode: merge. Any declarative base config applied via K8s is safely deep-merged with runtime configuration mutations (e.g. linked channels, active sessions) written by the agent inside the PVC at /home/openclaw/.openclaw/openclaw.json.
Stateful Memory: The agent's wisdom (MEMORY.md, SOUL.md, SQLite databases) resides in the persistent claim and survives pod restarts naturally.

2. Sidecar Mapping

The multi-container pod structure is managed natively by the operator controller:

Legay Pod Container	Operator Controller Replacement
`chromium-sidecar`	Managed natively under `spec.chromium` with autowired CDP endpoint
`sidecar-proxy`	Managed natively by operator gateway proxy sidecar
`git-sync`	Retained under `spec.sidecars` to fetch skills from private git repository
`skill-stabilizer`	Retained under `spec.sidecars` to copy skills to the flat PVC structure
`install-uv-python` (init)	Managed natively by the operator under `spec.runtimeDeps.python: true`

3. Multi-Agent Architecture & Agents-as-Code (ADR 0001)

Conductor: The main session runs as the lean front-of-house coordinator (SOUL.md), handling fast actions (< 2s) directly with MCP tools and delegating complex domain tasks via sessions_spawn.
Specialist Subagents & Telegram Forum Topics: 10 specialized subagents defined as code in the knowledge wiki and pinned to Telegram forum topics:
- 🏋️ agents/fitness.md (Topic 20 "Sport" — Garmin Connect 148 tools, Tacx Flux 2, home gym supersets)
- 🍳 agents/koch.md (Topic 21 "Kochen" — Ninja CREAMi Deluxe, Airfryer, KitchenAid, leftover utilization)
- 🩺 agents/hebamme.md (Topic 22 "Mila" — Baby development & sleep, pediatrician safety boundaries)
- ✈️ agents/travel.md (Topic 51 "Travel" — Vacation itineraries, packing lists, travel concierge)
- 🛒 agents/shopping.md (Topic 115 "Shopping" — Supermarket deals, Geizhals best prices, Bring! lists)
- 🏰 agents/regensburg.md (Topic 116 "Regensburg" — Stadtamhof insider, RVV, playgrounds, local dining)
- 🔍 agents/recherche.md (Topic 117 "Research" — Deep research, ALLRIS Stadtrat, Friday bridge tracking)
- 👨‍⚕️ agents/doktor.md (Topic 118 "Medizin" — Evidenzbasierte ärztliche Beratung, Laborwerte, Red-Flag Triage)
- 🧑‍💻 agents/itguy.md (Topic 119 "IT Guy" — Nerdy CS Hacker, K8s Ops via kubectl & RBAC, Git PRs, Prometheus Alert Responder)
- 🏡🎬 agents/grabengasse_media.md (Topic 164 "Grabengasse & Media" — Home Assistant, Hue, Sonos, Brother Drucker, Jellyfin & Spotify)
Inter-Agent Peer Escalation (A2A): Every subagent topic is configured with peer escalation authority via sessions_spawn(agentId="<target>", task="...") to consult sibling agents when cross-domain expertise is needed.
Modifying & Adding Agents: To update prompt logic, tone, or tool instructions for any agent, edit its markdown file directly in knowledge-wiki/agents/<name>.md and commit to git. No Kubernetes pod restarts required!
Multi-Turn Domain Stickiness: When a conversation spans multiple turns in a subagent domain (e.g. refining a recipe or planning a trip), the Conductor detects domain continuity and routes to the same agent with the state bridge .

🔧 Applying Configuration Changes

To perform modifications or rotate api keys:

Secrets: Edit string fields in openclaw.secret.yaml.
Declarative Base Config: Edit fields under spec.config.raw in openclaw-instance.secret.yaml.

Apply & Rollout: Apply the files. The operator tracks config hashes and performs an automated rolling update of the StatefulSet automatically (no manual restart needed!):

kubectl apply -f k8s/openclaw/openclaw.secret.yaml
kubectl apply -f k8s/openclaw/openclaw-instance.secret.yaml
kubectl apply -f k8s/openclaw/cronjob-wiki-backup.secret.yaml

Register / Sync Automations: Run setup-itguy-cron.sh to ensure the weekly health audit automation is registered in OpenClaw:
```
./k8s/openclaw/setup-itguy-cron.sh
```

4. 🗂️ The Three Core Repositories Architecture & Weekly Self-Audit

OpenClaw connects to three foundational Git repositories:

infrapuzzle (/home/node/.openclaw/repos/infrapuzzle on PVC):
- Scope: Source of truth for cluster infrastructure (haumdaucher), Kubespray bootstrap, K8s manifests, Terraform DNS, ESPHome IoT, and Architecture Decision Records (docs/adr/).
mop-skills (/home/node/mop-skills/mop-skills via git-sync sidecar):
- Scope: Custom Python skills, CLI utilities, and MCP bridges (openclaw-audit, garmin-auth, brother-printer, google-calendar, etc.).
knowledge-wiki (/home/node/.openclaw/wiki/main):
- Scope: Agents-as-code (agents/*.md), active task dispatch queue (tasks/antigravity.md), family knowledge vault, and audit archives (operations/audits/).

🩺 Autonomous Weekly Health Audit (`itguy-weekly-health-audit`)

Scheduled via OpenClaw Cron on Sundays at 03:00 Europe/Berlin (0 3 * * 0).
Executes uv run /home/node/mop-skills/mop-skills/skills/openclaw-audit/scripts/audit_openclaw.py --since 7d --write-report --add-task --git-push.
Correlates errors (pod stdout & session transcripts) with recent git commits across the 3 repositories.
Archives diagnostic reports into operations/audits/YYYY-Wxx.md.
Appends newly detected, actionable tasks into tasks/antigravity.md under ## 📥 Pending Tasks.
Telegram Notification Policy: Alerts Topic #IT Guy (thread 119) if new issues are filed; returns NO_REPLY for intentional silence when clean.

🚨 Troubleshooting & Live Verification

If the agent is offline or failing:

1. Verify Deployment Health

Ensure that the OpenClawInstance is successfully reconciled:

kubectl get openclawinstance openclaw -n openclaw
# Expected: PHASE=Running, READY=True

2. Verify Pod & Container States

Check that all 6 containers inside the StatefulSet are fully functional:

kubectl get pods -n openclaw -l app.kubernetes.io/instance=openclaw

3. Check Live Logs

Inspect the core gateway engine:

kubectl logs -n openclaw openclaw-0 -c openclaw --tail=100

Inspect the Chromium browser engine:

kubectl logs -n openclaw openclaw-0 -c chromium --tail=100

7.0 KiB Raw Blame History