You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
303 lines
7.2 KiB
Markdown
303 lines
7.2 KiB
Markdown
# Openclaw Helm Chart
|
|
|
|
Personal AI assistant with multi-channel support (WhatsApp, Telegram, Discord, and more) running on Kubernetes.
|
|
|
|
## TL;DR
|
|
|
|
```bash
|
|
helm install my-openclaw ./openclaw \
|
|
--set secrets.data.anthropicApiKey=sk-ant-xxx \
|
|
--set secrets.data.gatewayToken=$(openssl rand -hex 32)
|
|
```
|
|
|
|
## Introduction
|
|
|
|
This chart deploys Openclaw Gateway on a Kubernetes cluster using the Helm package manager.
|
|
|
|
**Important:** Openclaw is designed as a single-user personal assistant. The chart enforces `replicas: 1` and does not support horizontal scaling.
|
|
|
|
## Prerequisites
|
|
|
|
- Kubernetes 1.19+
|
|
- Helm 3.x
|
|
- PV provisioner support in the underlying infrastructure (for persistent storage)
|
|
- **Optional:** Ingress controller (NGINX, Traefik, etc.) for external access
|
|
- **Optional:** cert-manager for automatic TLS certificates
|
|
|
|
## Installing the Chart
|
|
|
|
### Basic Installation
|
|
|
|
```bash
|
|
helm install my-openclaw ./openclaw
|
|
```
|
|
|
|
### With Custom Values
|
|
|
|
```bash
|
|
helm install my-openclaw ./openclaw \
|
|
--values examples/values-production.yaml \
|
|
--set secrets.data.anthropicApiKey=sk-ant-xxx \
|
|
--set ingress.hosts[0].host=assistant.example.com
|
|
```
|
|
|
|
### From Examples
|
|
|
|
```bash
|
|
# Basic (local testing)
|
|
helm install my-openclaw ./openclaw -f examples/values-basic.yaml
|
|
|
|
# Production
|
|
helm install my-openclaw ./openclaw -f examples/values-production.yaml
|
|
|
|
# Fly.io-like setup
|
|
helm install my-openclaw ./openclaw -f examples/values-fly-like.yaml
|
|
```
|
|
|
|
## Uninstalling the Chart
|
|
|
|
```bash
|
|
helm uninstall my-openclaw
|
|
|
|
# Also delete PVCs (data will be lost)
|
|
kubectl delete pvc -l app.kubernetes.io/instance=my-openclaw
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Key Parameters
|
|
|
|
| Parameter | Description | Default |
|
|
|-----------|-------------|---------|
|
|
| `replicaCount` | Number of replicas (must be 1) | `1` |
|
|
| `image.repository` | Openclaw image repository | `openclaw/openclaw` |
|
|
| `image.tag` | Image tag | Chart appVersion |
|
|
| `gateway.bind` | Gateway binding mode (`loopback`, `lan`, `auto`) | `lan` |
|
|
| `gateway.port` | Gateway port | `18789` |
|
|
| `secrets.data.anthropicApiKey` | Anthropic API key | `""` |
|
|
| `secrets.data.openaiApiKey` | OpenAI API key | `""` |
|
|
| `secrets.data.gatewayToken` | Gateway authentication token (auto-generated if empty) | `""` |
|
|
| `persistence.enabled` | Enable persistent storage | `true` |
|
|
| `persistence.size` | PVC size | `10Gi` |
|
|
| `ingress.enabled` | Enable Ingress | `false` |
|
|
| `ingress.className` | Ingress class | `nginx` |
|
|
| `resources.limits.memory` | Memory limit | `2Gi` |
|
|
| `resources.requests.memory` | Memory request | `512Mi` |
|
|
|
|
### Full Values Reference
|
|
|
|
See [values.yaml](values.yaml) for all available parameters.
|
|
|
|
## Storage
|
|
|
|
The chart creates a StatefulSet with a persistent volume claim template that mounts storage at two locations:
|
|
|
|
- `/home/node/.openclaw` (subPath: `openclaw-state`) - Configuration, sessions, device identity, SQLite databases
|
|
- `/home/node/clawd` (subPath: `openclaw-workspace`) - Agent workspace files
|
|
|
|
**Storage Class:** By default, uses the cluster's default storage class. Override with `persistence.storageClass`.
|
|
|
|
**Size Recommendations:**
|
|
- Development/Testing: 5-10Gi
|
|
- Production (single user): 20Gi+
|
|
- Depends on session history and workspace usage
|
|
|
|
## Secrets Management
|
|
|
|
### Option 1: Inline Secrets (Development Only)
|
|
|
|
```bash
|
|
helm install my-openclaw ./openclaw \
|
|
--set secrets.data.anthropicApiKey=sk-ant-xxx \
|
|
--set secrets.data.gatewayToken=$(openssl rand -hex 32)
|
|
```
|
|
|
|
### Option 2: External Secret (Production)
|
|
|
|
Create a Kubernetes Secret:
|
|
|
|
```bash
|
|
kubectl create secret generic openclaw-secrets \
|
|
--from-literal=gatewayToken=$(openssl rand -hex 32) \
|
|
--from-literal=anthropicApiKey=sk-ant-xxx \
|
|
--from-literal=discordBotToken=MTQ...
|
|
```
|
|
|
|
Install with existing secret:
|
|
|
|
```bash
|
|
helm install my-openclaw ./openclaw \
|
|
--set secrets.create=false \
|
|
--set secrets.existingSecret=openclaw-secrets
|
|
```
|
|
|
|
### Option 3: External Secrets Operator
|
|
|
|
Use External Secrets Operator to sync from Vault, AWS Secrets Manager, etc.
|
|
|
|
## Ingress
|
|
|
|
### NGINX Ingress Controller
|
|
|
|
```yaml
|
|
ingress:
|
|
enabled: true
|
|
className: nginx
|
|
annotations:
|
|
cert-manager.io/cluster-issuer: letsencrypt-prod
|
|
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
|
|
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
|
|
nginx.ingress.kubernetes.io/websocket-services: "{{ include \"openclaw.fullname\" . }}"
|
|
hosts:
|
|
- host: assistant.example.com
|
|
paths:
|
|
- path: /
|
|
pathType: Prefix
|
|
tls:
|
|
- secretName: openclaw-tls
|
|
hosts:
|
|
- assistant.example.com
|
|
```
|
|
|
|
**Important:** WebSocket support requires extended timeouts (3600s recommended).
|
|
|
|
### Traefik
|
|
|
|
```yaml
|
|
ingress:
|
|
className: traefik
|
|
annotations:
|
|
traefik.ingress.kubernetes.io/router.entrypoints: websecure
|
|
traefik.ingress.kubernetes.io/router.tls: "true"
|
|
```
|
|
|
|
## Health Checks
|
|
|
|
The chart uses exec-based probes that run the CLI health command:
|
|
|
|
```yaml
|
|
livenessProbe:
|
|
exec:
|
|
command:
|
|
- sh
|
|
- -c
|
|
- node dist/index.js health --token "${CLAWDBOT_GATEWAY_TOKEN}" || exit 1
|
|
```
|
|
|
|
## Upgrading
|
|
|
|
```bash
|
|
# Pull latest chart changes
|
|
git pull
|
|
|
|
# Upgrade with current values
|
|
helm upgrade my-openclaw ./openclaw --reuse-values
|
|
|
|
# Upgrade with new values
|
|
helm upgrade my-openclaw ./openclaw -f values-production.yaml
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Pod Not Starting
|
|
|
|
```bash
|
|
# Check pod events
|
|
kubectl describe pod my-openclaw-0
|
|
|
|
# Check logs
|
|
kubectl logs my-openclaw-0
|
|
```
|
|
|
|
### OOM (Out of Memory)
|
|
|
|
Increase memory limits:
|
|
|
|
```yaml
|
|
resources:
|
|
limits:
|
|
memory: 4Gi
|
|
requests:
|
|
memory: 1Gi
|
|
```
|
|
|
|
**Note:** 512MB is too small for production. 2GB recommended minimum.
|
|
|
|
### PVC Not Binding
|
|
|
|
```bash
|
|
# Check PVC status
|
|
kubectl get pvc
|
|
|
|
# Check storage class
|
|
kubectl get storageclass
|
|
|
|
# Describe for events
|
|
kubectl describe pvc data-my-openclaw-0
|
|
```
|
|
|
|
### WebSocket Connections Timing Out
|
|
|
|
Ensure Ingress has WebSocket annotations:
|
|
|
|
```yaml
|
|
annotations:
|
|
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
|
|
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
|
|
```
|
|
|
|
### Gateway Lock File Issues
|
|
|
|
If the gateway won't start due to stale lock files:
|
|
|
|
```bash
|
|
kubectl exec my-openclaw-0 -- rm -f /home/node/.openclaw/gateway.*.lock
|
|
kubectl delete pod my-openclaw-0 # Restart pod
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Local Testing (Minikube/Kind/Docker Desktop)
|
|
|
|
```bash
|
|
# Build local image
|
|
docker build -t openclaw:local .
|
|
|
|
# Load into cluster (example for Minikube)
|
|
minikube image load openclaw:local
|
|
|
|
# Install chart
|
|
helm install test ./openclaw \
|
|
-f examples/values-basic.yaml \
|
|
--set image.repository=openclaw \
|
|
--set image.tag=local \
|
|
--set image.pullPolicy=Never
|
|
```
|
|
|
|
### Production Deployment
|
|
|
|
```bash
|
|
# Create external secret first
|
|
kubectl create secret generic openclaw-secrets \
|
|
--from-literal=gatewayToken=$(openssl rand -hex 32) \
|
|
--from-literal=anthropicApiKey=$ANTHROPIC_API_KEY
|
|
|
|
# Install with production values
|
|
helm install my-openclaw ./openclaw -f examples/values-production.yaml
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Openclaw Documentation](https://docs.clawd.bot)
|
|
- [Kubernetes Installation Guide](https://docs.clawd.bot/install/kubernetes)
|
|
- [GitHub Repository](https://github.com/openclaw/openclaw)
|
|
|
|
## Support
|
|
|
|
- [GitHub Issues](https://github.com/openclaw/openclaw/issues)
|
|
- [Documentation](https://docs.clawd.bot)
|
|
|
|
## License
|
|
|
|
See [LICENSE](https://github.com/openclaw/openclaw/blob/main/LICENSE)
|