# 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. Source    *   **Telegram**: Configured with `dmPolicy: "allowlist"` for users `306373425` and `255114390`.
    *   **Skills**: Enabled `nano-banana-pro` (Gemini image generation). Installed `uv` persistently into the PVC.
    *   **Configuration**: Streamlined `openclaw.secret.yaml`. Consolidated JSON into `ConfigMap`.
    *   **Status**: **Fully Functional** (Secure: Basic Auth + Gateway Token + Multi-LLM + Image Gen).
json`

### 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 main `openclaw` container identifies the persistent volume at `/home/node/.openclaw`.

### 3. Applying Changes
To update the configuration:
1. Modify the `openclaw.json` block in [openclaw.secret.yaml](file:///Users/moritz/src/infrapuzzle/k8s/openclaw/openclaw.secret.yaml).
2. Apply the manifest: `kubectl apply -f openclaw/openclaw.secret.yaml`
3. **Rotate Deployment**: You MUST restart the pod to trigger the `initContainer` bootstrap:
   `kubectl rollout restart deployment openclaw -n openclaw`

---

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

### `gateway`
Controls the main server behavior and security.
- `trustedProxies`: List of IPs to trust for `X-Forwarded-For` headers (e.g., `["127.0.0.1"]`).
- `controlUi.dangerouslyDisableDeviceAuth`: Set to `true` to allow login via token/password without device identity verification (useful for initial setup).
- `port`: Default `18789`. Controlled via `OPENCLAW_GATEWAY_PORT` env var in the manifest.

### `agents.defaults`
Global defaults for all agents launched by the gateway.
- `model.primary`: The default LLM (e.g., `google/gemini-flash-latest`).
- `model.fallbacks`: List of model IDs to use if the primary fail.
- `contextTokens`: Maximum context window (e.g., `200000`).

### `models.providers`
Definition of external LLM sources.
- **`ollama`**:
  - `baseUrl`: `http://127.0.0.1:11434` (proxied via sidecar).
  - `apiKey`: Required for discovery (e.g., `ollama-local`).
  - `models`: Array of model objects with `id`, `contextWindow`, etc.
- **`google`**: Built-in provider. Uses `GEMINI_API_KEY` environment variable.

### `channels`
Messaging platform integrations.
- **`telegram`**:
  - `enabled`: `true` | `false`.
  - `dmPolicy`: `pairing` (default) | `allowlist` (skip approval).
  - `allowFrom`: Array of numeric user IDs (e.g., `["306373425"]`) allowed to DM the bot.

### `plugins` (Extensions)
Platform extensions (e.g., WhatsApp, Telegram).
- `entries.<pluginId>.enabled`: Enable/disable specific extension logic.
- `entries.<pluginId>.config`: Plugin-specific settings object.

### `skills`
Modular tool capabilities.
- `entries.<skillKey>.env`: Environment variables injected into the skill run.

### 💡 Special Requirements
- **`nano-banana-pro`**: Requires the `uv` tool. It is installed at `/home/node/.openclaw/bin/uv` (on the PVC) and included in the system `PATH`.

## 🚨 Startup & Troubleshooting

### Investigating Issues
You can execute commands directly inside the running pod to inspect the environment or file system:
```bash
# Get the pod name
kubectl get pods -n openclaw

# Execute a command (e.g., check config)
kubectl exec -it -n openclaw <pod-name> -c openclaw -- cat /home/node/.openclaw/openclaw.json

# Check environment variables
kubectl exec -it -n openclaw <pod-name> -c openclaw -- env | grep OPENCLAW
```

### Applying Configuration Changes
Any change to `openclaw.secret.yaml` (ConfigMap or Deployment) requires a rollout restart to take effect:
```bash
kubectl apply -f k8s/openclaw/openclaw.secret.yaml
kubectl rollout restart deployment openclaw -n openclaw
```
Always verify the rollout status:
```bash
kubectl rollout status deployment openclaw -n openclaw
```