infrapuzzle/k8s/openclaw/AGENTS.md

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

---

🔧 Applying Configuration Changes

To perform modifications or rotate api keys:

1. Secrets: Edit string fields in openclaw.secret.yaml.
2. Declarative Base Config: Edit fields under spec.config.raw in openclaw-instance.secret.yaml.
3. 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
   

---

🚨 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