Latest state of openclaw and traefik
This commit is contained in:
Moritz Graf
+49
-49
@@ -1,69 +1,69 @@
|
||||
# OpenClaw Agent Guide
|
||||
# OpenClaw Agent Guide (Operator-Managed)
|
||||
|
||||
This document provides a comprehensive technical reference for AI agents to manage the **OpenClaw** deployment in this repository.
|
||||
This document provides a technical reference for AI agents managing the **OpenClaw** deployment in this repository.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture & Configuration Lifecycle
|
||||
|
||||
### 1. Status
|
||||
* **Telegram**: Configured with `dmPolicy: "allowlist"` for users `306373425` and `255114390`.
|
||||
* **Skills**: Integrated `gog` (Workspace), `nano-banana-pro` (Image Gen), and various utility skills.
|
||||
* **Authentication**: Multi-provider setup with Gemini CLI OAuth (Primary) and Gemini API Key (Backup).
|
||||
* **Ollama**: Removed from the deployment.
|
||||
The deployment has been migrated to the **OpenClaw Operator** framework.
|
||||
|
||||
### 2. Bootstrap Process
|
||||
OpenClaw uses an `initContainer` to bootstrap the configuration:
|
||||
1. The `openclaw-bootstrap-config` volume is mounted at `/mnt/config`.
|
||||
2. The `initContainer` copies `/mnt/config/openclaw.json` to the persistent data volume at `/mnt/data/openclaw.json`.
|
||||
3. The `initContainer` provisions authentication tokens (e.g., `google-gemini-cli.json`) from environment variables/secrets.
|
||||
4. The main `openclaw` container identifies the persistent volume at `/home/node/.openclaw`.
|
||||
### 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.
|
||||
|
||||
### 3. Gemini OAuth Setup & Sync
|
||||
This deployment uses a **local-to-remote** sync for Gemini OAuth:
|
||||
1. **Local Login**: The user runs `openclaw models auth login --provider google-gemini-cli` on their local machine.
|
||||
2. **Credential Capture**: This generates `~/.gemini/oauth_creds.json` locally.
|
||||
3. **Secret Update**: The JSON content from that file is copied into the `gemini-oauth-token` field of `openclaw.secret.yaml`.
|
||||
4. **Provisioning**: The `initContainer` in the K8s manifest reads the `GEMINI_OAUTH_TOKEN` env var (populated from the secret) and writes it to `/home/node/.openclaw/auth/google-gemini-cli.json`.
|
||||
### 2. Sidecar Mapping
|
||||
|
||||
### 4. Applying Changes
|
||||
To update the configuration or rotate tokens:
|
||||
1. Modify the relevant fields in [openclaw.secret.yaml](file:///Users/moritz/src/infrapuzzle/k8s/openclaw/openclaw.secret.yaml).
|
||||
2. Apply the manifest: `kubectl apply -f k8s/openclaw/openclaw.secret.yaml`
|
||||
3. **Rotate Deployment**: You MUST restart the pod to trigger the `initContainer` bootstrap and inject new env vars:
|
||||
`kubectl rollout restart deployment openclaw -n openclaw`
|
||||
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` |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Configuration Reference (`openclaw.json`)
|
||||
## 🔧 Applying Configuration Changes
|
||||
|
||||
### `models.providers`
|
||||
- **`google`**: Built-in provider. Uses `GEMINI_API_KEY`. See [GEMINI_AUTH_GUIDE.md](file:///Users/moritz/src/infrapuzzle/k8s/openclaw/GEMINI_AUTH_GUIDE.md).
|
||||
- **`google-gemini-cli`**: OAuth-based provider (Primary). Uses provisioned tokens.
|
||||
### `agents.defaults`
|
||||
- `model.primary`: `google-gemini-cli/gemini-3-flash-preview`
|
||||
- `model.fallbacks`: `["google/gemini-flash-latest"]`
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Gemini 3 requires `previewFeatures: true` in `~/.gemini/settings.json`, which is automatically provisioned by the `initContainer`. A **rollout restart** is required after any manifest change.
|
||||
|
||||
### `plugins`
|
||||
- `google-gemini-cli-auth`: MUST be enabled for the primary provider to function.
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Startup & Troubleshooting
|
||||
## 🚨 Troubleshooting & Live Verification
|
||||
|
||||
### Investigating Issues
|
||||
If the agent is offline or failing:
|
||||
|
||||
### 1. Verify Deployment Health
|
||||
Ensure that the `OpenClawInstance` is successfully reconciled:
|
||||
```bash
|
||||
# Check config
|
||||
kubectl exec -it -n openclaw deployment/openclaw -c openclaw -- cat /home/node/.openclaw/openclaw.json
|
||||
|
||||
# Check auth tokens
|
||||
kubectl exec -it -n openclaw deployment/openclaw -c openclaw -- ls -la /home/node/.openclaw/auth/
|
||||
kubectl get openclawinstance openclaw -n openclaw
|
||||
# Expected: PHASE=Running, READY=True
|
||||
```
|
||||
|
||||
### Applying Configuration Changes
|
||||
### 2. Verify Pod & Container States
|
||||
Check that all 6 containers inside the StatefulSet are fully functional:
|
||||
```bash
|
||||
kubectl apply -f k8s/openclaw/openclaw.secret.yaml
|
||||
kubectl rollout restart deployment openclaw -n openclaw
|
||||
kubectl rollout status deployment openclaw -n openclaw
|
||||
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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user