3.4 KiB

Raw Blame History

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

Telegram: Configured with dmPolicy: "allowlist" for users 306373425 and 255114390.
Skills: Integrated gog (Workspace), nano-banana-pro (Image Gen), and various utility skills.
Authentication: Multi-provider setup with Gemini CLI OAuth (Primary) and Gemini API Key (Backup).
Ollama: Removed from the deployment.

2. Bootstrap Process

OpenClaw uses an initContainer to bootstrap the configuration:

The openclaw-bootstrap-config volume is mounted at /mnt/config.
The initContainer copies /mnt/config/openclaw.json to the persistent data volume at /mnt/data/openclaw.json.
The initContainer provisions authentication tokens (e.g., google-gemini-cli.json) from environment variables/secrets.
The main openclaw container identifies the persistent volume at /home/node/.openclaw.

3. Gemini OAuth Setup & Sync

This deployment uses a local-to-remote sync for Gemini OAuth:

Local Login: The user runs openclaw models auth login --provider google-gemini-cli on their local machine.
Credential Capture: This generates ~/.gemini/oauth_creds.json locally.
Secret Update: The JSON content from that file is copied into the gemini-oauth-token field of openclaw.secret.yaml.
Provisioning: The initContainer in the K8s manifest reads the GEMINI_OAUTH_TOKEN env var (populated from the secret) and writes it to /home/node/.openclaw/auth/google-gemini-cli.json.

4. Applying Changes

To update the configuration or rotate tokens:

Modify the relevant fields in openclaw.secret.yaml.
Apply the manifest: kubectl apply -f k8s/openclaw/openclaw.secret.yaml
Rotate Deployment: You MUST restart the pod to trigger the initContainer bootstrap and inject new env vars: kubectl rollout restart deployment openclaw -n openclaw

🔧 Configuration Reference (`openclaw.json`)

`models.providers`

google: Built-in provider. Uses GEMINI_API_KEY. See GEMINI_AUTH_GUIDE.md.
google-gemini-cli: OAuth-based provider (Primary). Uses provisioned tokens.

`agents.defaults`

model.primary: google-gemini-cli/gemini-3-flash-preview
model.fallbacks: ["google/gemini-flash-latest"]

[!IMPORTANT] Gemini 3 requires previewFeatures: true in ~/.gemini/settings.json, which is automatically provisioned by the initContainer. A rollout restart is required after any manifest change.

`plugins`

google-gemini-cli-auth: MUST be enabled for the primary provider to function.

🚨 Startup & Troubleshooting

Investigating Issues

# Check config
kubectl exec -it -n openclaw deployment/openclaw -c openclaw -- cat /home/node/.openclaw/openclaw.json

# Check auth tokens
kubectl exec -it -n openclaw deployment/openclaw -c openclaw -- ls -la /home/node/.openclaw/auth/

Applying Configuration Changes

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

3.4 KiB Raw Blame History