infrapuzzle/k8s/openclaw/AGENTS.md

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.
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:

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

kubectl apply -f k8s/openclaw/openclaw.secret.yaml
kubectl rollout restart deployment openclaw -n openclaw

Always verify the rollout status:

kubectl rollout status deployment openclaw -n openclaw