94 lines
4.0 KiB
Markdown
94 lines
4.0 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. 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
|
|
```
|