Files

T

Moritz Graf e45dbc2e19 feat(sasch40): improve Act III, add state persistence and fix portraits

- Fix character portrait crops and version assets to portrait_v2, ensuring correct identities (resolving Nat/Verena mismatch)
- Update Schankraum scene image and configure Nginx cache-control to prevent stale asset caching
- Make secret beer tap completely invisible in tavern until clicked
- Reposition room hotspots in Act III to eliminate overlapping click targets
- Add exit button [✕] to Bavarian Gstanzl duel minigame
- Implement localStorage persistence in gameStore to maintain progress across page reloads
- Enable clean game state and storage reset when clicking "Nochmal spielen"
- Expand automated playtest script to cover Nat dialogue, duel exit, reload persistence, and game restart

2026-09-24 11:03:22 +02:00

7.3 KiB

Raw Blame History

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 & Incident Playbook

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 with symptom, root cause, resolution, and how to avoid recurrence.

For known issues, resolved bugs, and specific failure playbooks, consult TROUBLESHOOTING.md.

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.3 KiB Raw Blame History