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 of Truth

The configuration for OpenClaw is centralized in the openclaw-bootstrap-config ConfigMap within 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.
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.