# OpenClaw Agent Guide

This document provides a comprehensive technical reference for AI agents to manage 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.

### 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`.

### 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`.

### 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`

---

## 🔧 Configuration Reference (`openclaw.json`)

### `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.

---

## 🚨 Startup & Troubleshooting

### Investigating Issues
```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/
```

### Applying Configuration Changes
```bash
kubectl apply -f k8s/openclaw/openclaw.secret.yaml
kubectl rollout restart deployment openclaw -n openclaw
kubectl rollout status deployment openclaw -n openclaw
```