70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
# 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](file:///Users/moritz/src/infrapuzzle/k8s/openclaw/openclaw.secret.yaml).
|
|
2. **Declarative Base Config**: Edit fields under `spec.config.raw` in [openclaw-instance.secret.yaml](file:///Users/moritz/src/infrapuzzle/k8s/openclaw/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!):
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
kubectl get pods -n openclaw -l app.kubernetes.io/instance=openclaw
|
|
```
|
|
|
|
### 3. Check Live Logs
|
|
Inspect the core gateway engine:
|
|
```bash
|
|
kubectl logs -n openclaw openclaw-0 -c openclaw --tail=100
|
|
```
|
|
|
|
Inspect the Chromium browser engine:
|
|
```bash
|
|
kubectl logs -n openclaw openclaw-0 -c chromium --tail=100
|
|
```
|