70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# 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
|
|
```
|