# 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 of Truth
The configuration for OpenClaw is centralized in the `openclaw-bootstrap-config` **ConfigMap** within [openclaw.secret.yaml](file:///Users/moritz/src/infrapuzzle/k8s/openclaw/openclaw.secret.yaml).
- **Active File**: `openclaw.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.
- `allowBundled`: Allowlist of built-in skills.
- `load.extraDirs`: Additional paths to scan for `SKILL.md` files.
- `entries.<skillKey>.env`: Environment variables injected into the skill run.