# OpenClaw Helm Chart
Helm chart for [OpenClaw](https://openclaw.ai/) (gateway). Deploys a single-instance StatefulSet with persistent storage, secrets management, and an optional [LiteLLM](https://github.com/BerriAI/litellm) proxy for model routing.
## Requirements
- Helm v3
- A Kubernetes cluster with PersistentVolume support (optional if persistence is disabled)
## Install
Charts are published as OCI artifacts in GHCR.
1) Create a Telegram bot via [@BotFather](https://t.me/BotFather):
- Message [@BotFather](https://t.me/BotFather), send `/newbot`, and follow the prompts
- Save the token: `export telegramBotToken=<your-token>`
1) Generate a gateway token:
```bash
export gatewayToken=$(openssl rand -hex 32)
```
1) Install the chart:
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--create-namespace --namespace openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramBotToken=$telegramBotToken
```
This deploys the OpenClaw gateway and a LiteLLM proxy with Github Copilot provider (enabled by default).
1) (Alternative) Use a specific model provider (e.g. Anthropic):
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--create-namespace --namespace openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramBotToken=$telegramBotToken \
--set litellm.secrets.provider=anthropic \
--set litellm.secrets.apiKey=<your-api-key> \
--set litellm.secrets.apiBase=<your-api-base> \
--set litellm.model=claude-opus-4.6
```
1) Access the portal:
```bash
kubectl --namespace openclaw port-forward openclaw-0 18789:18789
```
Then open <http://localhost:18789/?token=$gatewayToken> in your browser.
1) (Optional) View the Chrome browser GUI via noVNC:
```bash
kubectl --namespace openclaw port-forward openclaw-0 6080:6080
```
Then open <http://localhost:6080/vnc.html> in your browser to see the Chrome desktop.
## Browser GUI
Chrome runs in headed mode inside a virtual display. Access the desktop via [noVNC](https://novnc.com/) on port **6080** to watch browser automation in real time.
<details>
<summary>How it works</summary>
supervisord manages the full GUI stack inside the container:
1. **Xvfb** โ virtual framebuffer (display `:99`)
2. **Fluxbox** โ lightweight window manager
3. **x11vnc** โ VNC server on port `5900` (localhost only)
4. **websockify + noVNC** โ bridges VNC to WebSocket, served on port `6080`
5. **OpenClaw gateway** โ launches Chrome against `DISPLAY=:99`
All processes auto-restart on failure.
Environment variables:
| Variable | Default | Description |
|---|---|---|
| `DISPLAY_NUM` | `99` | X display number |
| `SCREEN_RESOLUTION` | `1920x1080x24` | Virtual screen resolution |
| `VNC_PORT` | `5900` | Internal VNC port (not exposed externally) |
| `NOVNC_PORT` | `6080` | noVNC web UI port |
</details>
## Tailscale
[Tailscale](https://tailscale.com/) integration for secure access to the gateway without exposing public ports. When enabled, each StatefulSet pod registers as a unique device on your Tailscale network.
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramBotToken=$telegramBotToken \
--set tailscale.enabled=true \
--set secrets.tailscaleAuthKey=tskey-auth-xxxxx \
--set tailscale.hostname=openclaw
```
After deployment, access the gateway via its Tailscale hostname (e.g. `openclaw-0`) or Tailscale IP.
<details>
<summary>Configuration</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `tailscale.enabled` | `false` | Enable Tailscale mesh VPN |
| `tailscale.hostname` | `""` | Hostname prefix on the Tailscale network. Each pod appends its ordinal: `<hostname>-0`, `<hostname>-1`, etc. If empty, uses the pod name. |
| `tailscale.userspace` | `false` | Use userspace networking instead of kernel networking (no NET_ADMIN needed, but requires `tailscale.serve.enabled`) |
| `tailscale.acceptDns` | `false` | Accept DNS configuration from the Tailscale network |
| `tailscale.extraArgs` | `""` | Extra arguments passed to `tailscale up` (e.g. `--advertise-routes=10.96.0.0/12`) |
| `tailscale.serve.enabled` | `false` | Enable `tailscale serve` to proxy the gateway with Tailscale HTTPS certificates |
| `tailscale.serve.port` | `""` | Port to proxy (defaults to gateway port) |
| `secrets.tailscaleAuthKey` | `""` | Tailscale auth key (**required** when `tailscale.enabled` is `true`) |
</details>
<details>
<summary>How it works</summary>
- **Per-Pod Node model**: Each StatefulSet pod registers as a unique Tailscale device, so multi-replica works without routing conflicts.
- **Kernel networking** (default): Creates a real TUN interface so services are directly reachable via the Tailscale IP. The chart automatically adds `NET_ADMIN` capability. Set `tailscale.userspace: true` for userspace networking (no capability needed, but requires `tailscale.serve.enabled` for access).
- **Ephemeral state**: Tailscale state uses `emptyDir` โ pods re-authenticate on restart using a reusable auth key. Use a **Reusable + Ephemeral** key from [Tailscale admin](https://login.tailscale.com/admin/settings/keys).
- **HTTPS via Tailscale Serve**: Enable `tailscale.serve.enabled` to get automatic HTTPS certificates from Tailscale for the gateway.
</details>
## Skills
The container image ships with built-in **skills** โ structured instruction sets that teach the OpenClaw agent how to operate external coding tools as managed sub-agents. Skills are installed at `~/.openclaw/skills/` inside the container.
### Included Skills
| Skill | Description |
|-------|-------------|
| `claude-skill` | Operate Claude Code as a managed coding agent (worktree isolation, tmux sessions, smart retries) |
| `codex-skill` | Operate Codex CLI as a managed coding agent (same workflow, Codex-specific flags) |
Built-in skills are synced from the container image to the persistent volume on every pod start, so upgrading the chart or image automatically updates them.
### Adding Custom Skills
Add custom skills by placing them in the persistent volume at `~/.openclaw/skills/<skill-name>/`. You can copy them into the running pod:
```bash
kubectl -n openclaw cp ./my-skill openclaw-0:/home/vibe/.openclaw/skills/my-skill
```
Alternatively, mount a ConfigMap as a skill directory via `extraVolumes` and `extraVolumeMounts`. This works for simple skills consisting of a single `SKILL.md`:
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set 'extraVolumes[0].name=custom-skills' \
--set 'extraVolumes[0].configMap.name=my-skills' \
--set 'extraVolumeMounts[0].name=custom-skills' \
--set 'extraVolumeMounts[0].mountPath=/home/vibe/.openclaw/skills/my-skill' \
--set 'extraVolumeMounts[0].readOnly=true'
```
### External Skills (PVC / NFS)
For skills stored outside the main persistent volume โ such as shared skill packs on a separate PVC or NFS share โ use `openclaw.skills.volumes` to mount them and auto-wire them into the config:
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramBotToken=$telegramBotToken \
--set 'openclaw.skills.volumes[0].name=shared-skills' \
--set 'openclaw.skills.volumes[0].mountPath=/skills/shared' \
--set 'openclaw.skills.volumes[0].persistentVolumeClaim.claimName=shared-skills-pvc'
```
Each volume entry mounts a read-only volume and automatically adds its `mountPath` to the `skills.load.extraDirs` list in `openclaw.json`. Any Kubernetes volume type works (PVC, NFS, hostPath, etc.):
```yaml
openclaw:
skills:
volumes:
- name: shared-skills
mountPath: /skills/shared
persistentVolumeClaim:
claimName: shared-skills-pvc
- name: nfs-skills
mountPath: /skills/nfs
nfs:
server: 10.0.0.1
path: /exported/skills
```
For skill directories already on the main PVC, use `extraDirs` instead:
```yaml
openclaw:
skills:
load:
extraDirs:
- /home/vibe/my-project/skills
```
<details>
<summary>Skills loading configuration</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `openclaw.skills.load.extraDirs` | `[]` | Additional directories to load skills from |
| `openclaw.skills.load.watch` | `true` | Watch skill files for changes (auto-reload) |
| `openclaw.skills.load.watchDebounceMs` | `250` | Debounce time in ms for file change detection |
| `openclaw.skills.volumes` | `[]` | PVC/NFS volumes containing external skills (auto-mounted and auto-wired) |
Each path in `extraDirs` (or auto-wired from `volumes`) must follow the standard skill directory structure: `<dir>/<skill-name>/SKILL.md`. External skills are lowest priority โ workspace and managed skills take precedence.
For an Azure Blob NFS example, see [`examples/external-skills-pv.yaml`](examples/external-skills-pv.yaml) and [`examples/external-skills-pvc.yaml`](examples/external-skills-pvc.yaml).
</details>
See [`skills/README.md`](skills/README.md) for skill structure and authoring details.
## Memory
OpenClaw supports **semantic memory search** over the agent workspace (`MEMORY.md` + `memory/*.md` + session transcripts). When configured, the agent can recall prior conversations, decisions, and notes using natural-language queries via the `memory_search` tool.
Memory search requires an **embedding service** (e.g. OpenAI, Azure, Cohere) to generate vector embeddings for indexed content. Embedding credentials are stored in the **LiteLLM Secret** and routed through the LiteLLM proxy โ they never appear in `openclaw.json` (a plain ConfigMap). Configure via `litellm.secrets.embedding*` values:
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--create-namespace --namespace openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set litellm.secrets.provider=anthropic \
--set litellm.secrets.apiKey=<your-api-key> \
--set litellm.model=claude-opus-4.6 \
--set secrets.telegramBotToken=$telegramBotToken \
--set litellm.secrets.embeddingProvider=openai \
--set litellm.secrets.embeddingApiKey=<your-openai-api-key>
```
To use a custom embedding endpoint (e.g. Azure OpenAI or a self-hosted service), also set `embeddingApiBase`:
```bash
--set litellm.secrets.embeddingApiBase=https://my-endpoint.openai.azure.com/openai/v1/
```
<details>
<summary>Configuration details</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `litellm.secrets.embeddingProvider` | `openai` | Embedding provider (`openai`, `azure`, `cohere`, `voyage`, `mistral`, โฆ) |
| `litellm.secrets.embeddingApiKey` | `""` | API key for the embedding provider (**required** to enable memory search) |
| `litellm.secrets.embeddingApiBase` | `""` | Base URL for the embedding provider (optional; omit for default provider endpoint) |
| `openclaw.memorySearch.model` | `text-embedding-3-small` | Embedding model name |
| `openclaw.memorySearch.extraPaths` | `[]` | Additional paths to index (directories or files, Markdown only) |
Memory search is **only enabled** when `litellm.enabled` is `true` and `litellm.secrets.embeddingApiKey` is set. The embedding provider may be different from the main chat model provider โ for example, you can run `github_copilot` for chat and `openai` for embeddings. When enabled, the chart automatically configures:
- **Hybrid search** (BM25 keyword + vector similarity) with 70/30 weighting
- **Embedding cache** (up to 50,000 entries) to avoid re-embedding unchanged content
- **Session memory** indexing for conversation recall
- **File watching** for automatic re-indexing on workspace changes
</details>
<details>
<summary>Index and status commands</summary>
After deploying with memory search enabled, it is recommended to use these commands to manage the memory index (especially when you have set memorySearch.extraPaths) :
**Build the index** (run after first adding files to the workspace):
```bash
kubectl -n openclaw exec -it openclaw-0 -- openclaw memory index --verbose
```
This scans `MEMORY.md`, `memory/*.md`, and any `extraPaths`, generates embeddings, and stores them in a local SQLite database. The `--verbose` flag prints per-phase details including provider, model, sources, and batch activity.
**Check memory status:**
```bash
kubectl -n openclaw exec -it openclaw-0 -- openclaw memory status
```
Shows the current state of the memory index: indexed file count, embedding provider/model, store location, and whether the index is up-to-date. Add `--deep` to probe vector and embedding availability, or `--deep --index` to also trigger a reindex if the store is dirty.
</details>
## Upgrade / Uninstall
```bash
# Upgrade
helm upgrade openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--namespace openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramBotToken=$telegramBotToken
# Uninstall
helm uninstall openclaw --namespace openclaw
```
## LiteLLM Proxy
The chart includes a [LiteLLM](https://github.com/BerriAI/litellm) proxy between OpenClaw and model providers, enabled by default (`litellm.enabled: true`).
LiteLLM provides:
1. **Provider decoupling** -- OpenClaw talks only to the local LiteLLM endpoint. Switching providers (e.g. GitHub Copilot to Anthropic) requires only a Helm values change.
2. **Credential isolation** -- API keys (both chat model and embedding) live in the LiteLLM Secret and are never injected into the OpenClaw container or ConfigMap. OpenClaw authenticates to LiteLLM with a dummy token over the cluster-internal network.
<details>
<summary>How it works</summary>
- LiteLLM runs as a separate Deployment with its own Service (`<release>-litellm:4000`)
- The OpenClaw ConfigMap (`openclaw.json`) is automatically configured to route model requests through the LiteLLM proxy
- LiteLLM handles provider-specific API translation (Anthropic, OpenAI, GitHub Copilot, etc.)
- Provider credentials live exclusively in the `<release>-litellm` Secret and are only mounted into the LiteLLM pod
</details>
<details>
<summary>Provider configuration</summary>
Set the model provider via `litellm.secrets`:
| Provider | `litellm.secrets.provider` | `litellm.secrets.apiKey` | Notes |
|---|---|---|---|
| GitHub Copilot | `github_copilot` (default) | Not needed | Uses editor auth headers |
| Anthropic | `anthropic` | Required | Direct Anthropic API |
| OpenAI | `openai` | Required | Direct OpenAI API |
For providers with custom endpoints, set `litellm.secrets.apiBase` to the base URL.
</details>
<details>
<summary>Model selection</summary>
Set `litellm.model` to configure which model to proxy (default: `claude-opus-4.6`). The API format in `openclaw.json` is automatically determined:
- Models containing `claude` (e.g. `claude-opus-4.6`, `vertex_ai/claude-opus-4-6`) use `anthropic-messages`
- Models prefixed with `gpt` use `openai-responses`
- All other models use `openai-completions`
</details>
<details>
<summary>Custom LiteLLM config</summary>
To override the built-in config entirely, set `litellm.configOverride` with your complete LiteLLM YAML config.
</details>
## Values and configuration
### Quick reference
| Value | Default | Description |
|-------|---------|-------------|
| `secrets.openclawGatewayToken` | `""` | **Required.** Gateway authentication token |
| `litellm.enabled` | `true` | Enable LiteLLM proxy for model routing |
| `litellm.model` | `claude-opus-4.6` | Model to proxy through LiteLLM |
| `litellm.secrets.provider` | `github_copilot` | Model provider (`github_copilot`, `anthropic`, `openai`) |
| `persistence.enabled` | `true` | Enable persistent storage |
| `persistence.size` | `10Gi` | Storage size for OpenClaw data |
| `ingress.enabled` | `false` | Enable Ingress for external access |
| `service.type` | `ClusterIP` | Service type (`ClusterIP`, `NodePort`, `LoadBalancer`) |
| `tailscale.enabled` | `false` | Enable Tailscale mesh VPN for secure access |
See dedicated sections below for [Secrets](#secrets), [Messaging Platforms](#messaging-platforms), [Web Search](#web-search), and [LiteLLM Proxy](#litellm-proxy).
<details>
<summary>Image and replicas</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `replicaCount` | `1` | Must be 1 (OpenClaw is single-instance) |
| `image.repository` | `ghcr.io/feiskyer/openclaw-gateway` | Container image |
| `image.tag` | `""` | Image tag (defaults to chart appVersion) |
| `image.pullPolicy` | `Always` | Image pull policy |
| `imagePullSecrets` | `[]` | Pull secrets for private registries |
</details>
<details>
<summary>Service and networking</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `service.type` | `ClusterIP` | Service type |
| `service.port` | `18789` | Service port |
| `service.nodePort` | `null` | NodePort (when type is NodePort) |
| `ingress.enabled` | `false` | Enable Ingress |
| `ingress.className` | `""` | Ingress class name |
| `ingress.hosts` | `[{host: openclaw.local, ...}]` | Ingress hosts |
| `ingress.tls` | `[]` | TLS configuration |
</details>
<details>
<summary>Resources and probes</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `resources.requests.cpu` | `250m` | CPU request |
| `resources.requests.memory` | `1Gi` | Memory request |
| `resources.limits.cpu` | `2000m` | CPU limit |
| `resources.limits.memory` | `8Gi` | Memory limit |
| `livenessProbe.enabled` | `true` | Enable liveness probe |
| `readinessProbe.enabled` | `true` | Enable readiness probe |
| `startupProbe.enabled` | `false` | Enable startup probe |
</details>
<details>
<summary>Service account and security</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `serviceAccount.create` | `true` | Create service account |
| `serviceAccount.role` | `""` | Bind to ClusterRole (`view`, `cluster-admin`, or empty) |
| `podSecurityContext.runAsNonRoot` | `true` | Run as non-root user |
| `securityContext.allowPrivilegeEscalation` | `true` | Allow privilege escalation (required for sudo) |
| `securityContext.capabilities.add` | `[CAP_SETUID, CAP_SETGID]` | Capabilities for sudo |
</details>
<details>
<summary>Scheduling and availability</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `nodeSelector` | `{}` | Node selector |
| `tolerations` | `[]` | Pod tolerations |
| `affinity` | `{}` | Pod affinity rules |
| `topologySpreadConstraints` | `[]` | Topology spread constraints |
| `podDisruptionBudget.enabled` | `false` | Enable PDB |
</details>
<details>
<summary>Extensions</summary>
| Value | Default | Description |
|-------|---------|-------------|
| `extraEnv` | `[]` | Extra environment variables |
| `extraEnvFrom` | `[]` | Extra env from secrets/configmaps |
| `extraVolumes` | `[]` | Extra volumes |
| `extraVolumeMounts` | `[]` | Extra volume mounts |
| `initContainers` | `[]` | Additional init containers |
| `sidecars` | `[]` | Sidecar containers |
</details>
### Preset values files
| File | Use case |
|------|----------|
| `values.yaml` | Full defaults with security hardening |
| `values-minimal.yaml` | CI/testing (no security context, no persistence) |
| `values-development.yaml` | Local dev (NodePort, relaxed security, debug logging) |
| `values-production.yaml` | Production (Ingress + TLS, anti-affinity, backup annotations) |
## Persistence and data directory
Persistence is enabled by default (`persistence.enabled: true`) using the cluster's default StorageClass.
<details>
<summary>Storage configuration details</summary>
- Data volume mounted at `/home/vibe/.openclaw` (`OPENCLAW_STATE_DIR`).
- An init container seeds the volume from the image when the PVC is empty.
- Config (`openclaw.json`) is seeded from the ConfigMap if not already present.
- When `persistence.enabled` is `false`, an `emptyDir` volume is used instead of a PVC.
- To use a pre-provisioned volume, set `persistence.existingClaim`.
- LiteLLM has its own PVC (`litellm.persistence.*`) mounted at `~/.config/litellm`.
</details>
<details>
<summary>Azure File storage (permission fix)</summary>
Azure File (SMB) mounts don't support POSIX ownership natively, so the default StorageClass will cause permission errors for the non-root `vibe` user (UID 1024). Use the provided custom StorageClass that sets the correct `uid`/`gid` and file modes via mount options.
1) Create the StorageClass:
```bash
kubectl apply -f https://raw.githubusercontent.com/feiskyer/openclaw-kubernetes/main/examples/azurefile-storageclass.yaml
```
2) Install the chart with both PVs using the custom StorageClass and `ReadWriteMany` access mode:
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--create-namespace --namespace openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramBotToken=$telegramBotToken \
--set persistence.storageClass=azurefile-openclaw \
--set persistence.accessMode=ReadWriteMany \
--set litellm.persistence.storageClass=azurefile-openclaw \
--set litellm.persistence.accessMode=ReadWriteMany
```
The StorageClass configures:
- `uid=1024` / `gid=1024` โ matches the `vibe` user inside the container
- `dir_mode=0755` / `file_mode=0755` โ least-privilege file permissions
- `mfsymlinks` โ enables symlink support (required for node_modules)
- `nobrl` โ disables byte-range locks (avoids issues with SQLite)
- `Premium_LRS` โ premium SSD-backed Azure File shares
</details>
## Secrets
Two modes:
1) Set values under `secrets.*` and let the chart create a Secret.
2) Reference an existing secret via `secrets.existingSecret`.
<details>
<summary>Expected keys for an existing secret</summary>
- `OPENCLAW_GATEWAY_TOKEN` (required)
- `TELEGRAM_BOT_TOKEN` (optional)
- `DISCORD_BOT_TOKEN` (optional)
- `SLACK_BOT_TOKEN` (optional)
- `SLACK_APP_TOKEN` (optional)
- `FEISHU_APP_ID` (optional)
- `FEISHU_APP_SECRET` (optional)
- `MSTEAMS_APP_ID` (optional)
- `MSTEAMS_APP_PASSWORD` (optional)
- `MSTEAMS_TENANT_ID` (optional)
- `BRAVE_API_KEY` (optional)
- `PERPLEXITY_API_KEY` (optional)
- `TAILSCALE_AUTH_KEY` (optional, required when `tailscale.enabled` is `true`)
</details>
`secrets.openclawGatewayToken` is required when not using `secrets.existingSecret`.
LiteLLM has its own secret (`<release>-litellm`) configured via `litellm.secrets.*`:
| Key | Description |
|-----|-------------|
| `apiKey` | API key for the main chat model provider |
| `apiBase` | Base URL for the main chat model provider (optional) |
| `embeddingApiKey` | API key for the embedding provider (enables memory search when set) |
| `embeddingApiBase` | Base URL for the embedding provider (optional) |
## Messaging Platforms
OpenClaw supports multiple messaging platforms. Configure credentials via `secrets.*` values or an existing secret.
<details>
<summary>Discord</summary>
| Value | Environment Variable | Description |
|-------|---------------------|-------------|
| `secrets.discordBotToken` | `DISCORD_BOT_TOKEN` | Bot token from Discord Developer Portal |
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.discordBotToken=<your-discord-bot-token>
```
๐ [Discord Setup Guide](https://docs.openclaw.ai/channels/discord)
</details>
<details>
<summary>Telegram</summary>
| Value | Environment Variable | Description |
|-------|---------------------|-------------|
| `secrets.telegramBotToken` | `TELEGRAM_BOT_TOKEN` | Bot token from [@BotFather](https://t.me/BotFather) |
| `secrets.telegramTokenFile` | โ | File path to read bot token from (alternative to env var) |
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramBotToken=<your-telegram-bot-token>
```
To restrict which Telegram users can DM the bot, set `openclaw.dmAccess`. Get your numeric user ID from [@userinfobot](https://t.me/userinfobot):
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramBotToken=<your-telegram-bot-token> \
--set openclaw.dmAccess.policy=allowlist \
--set-json 'openclaw.dmAccess.allowFrom.telegram=["tg:123456789","@username"]'
```
For production deployments, consider using `telegramTokenFile` instead of `telegramBotToken` to avoid exposing the token in pod specs. Mount a Kubernetes Secret as a file and point `telegramTokenFile` to it:
```bash
# Create a secret with the token file
kubectl -n openclaw create secret generic telegram-token \
--from-literal=token=<your-telegram-bot-token>
# Install with tokenFile + volume mount
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.telegramTokenFile=/etc/openclaw-secrets/token \
--set 'extraVolumes[0].name=telegram-token' \
--set 'extraVolumes[0].secret.secretName=telegram-token' \
--set 'extraVolumeMounts[0].name=telegram-token' \
--set 'extraVolumeMounts[0].mountPath=/etc/openclaw-secrets' \
--set 'extraVolumeMounts[0].readOnly=true'
```
๐ [Telegram Setup Guide](https://docs.openclaw.ai/channels/telegram)
</details>
<details>
<summary>Slack</summary>
| Value | Environment Variable | Description |
|-------|---------------------|-------------|
| `secrets.slackBotToken` | `SLACK_BOT_TOKEN` | Bot user OAuth token (`xoxb-...`) |
| `secrets.slackAppToken` | `SLACK_APP_TOKEN` | App-level token (`xapp-...`) |
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.slackBotToken=xoxb-... \
--set secrets.slackAppToken=xapp-...
```
To restrict which Slack users can DM the bot, set `openclaw.dmAccess`. Find user IDs in Slack via **Profile โ Copy member ID** (format: `U053FP6RAMA`):
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.slackBotToken=xoxb-... \
--set secrets.slackAppToken=xapp-... \
--set openclaw.dmAccess.policy=allowlist \
--set-json 'openclaw.dmAccess.allowFrom.slack=["U053FP6RAMA"]'
```
๐ [Slack Setup Guide](https://docs.openclaw.ai/channels/slack)
</details>
<details>
<summary>Feishu (Lark)</summary>
| Value | Environment Variable | Description |
|-------|---------------------|-------------|
| `secrets.feishuAppId` | `FEISHU_APP_ID` | App ID (`cli_xxx`) from Feishu Open Platform |
| `secrets.feishuAppSecret` | `FEISHU_APP_SECRET` | App Secret (keep private) |
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.feishuAppId=cli_xxx \
--set secrets.feishuAppSecret=<your-app-secret>
```
๐ [Feishu Setup Guide](https://docs.openclaw.ai/channels/feishu)
</details>
<details>
<summary>Microsoft Teams</summary>
| Value | Environment Variable | Description |
|-------|---------------------|-------------|
| `secrets.msteamsAppId` | `MSTEAMS_APP_ID` | Azure Bot Application ID |
| `secrets.msteamsAppPassword` | `MSTEAMS_APP_PASSWORD` | Client secret from Azure Portal |
| `secrets.msteamsTenantId` | `MSTEAMS_TENANT_ID` | Directory (tenant) ID |
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.msteamsAppId=<azure-app-id> \
--set secrets.msteamsAppPassword=<client-secret> \
--set secrets.msteamsTenantId=<tenant-id>
```
๐ [Microsoft Teams Setup Guide](https://docs.openclaw.ai/channels/msteams)
</details>
## Web Search
OpenClaw supports web search via Brave or Perplexity. When an API key is configured, `tools.web.search` is automatically enabled in `openclaw.json`.
<details>
<summary>Brave Search</summary>
Structured results (title, URL, snippet) with a free tier available.
| Value | Environment Variable | Description |
|-------|---------------------|-------------|
| `secrets.braveApiKey` | `BRAVE_API_KEY` | Brave Search API key |
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.braveApiKey=<your-brave-api-key>
```
</details>
<details>
<summary>Perplexity</summary>
AI-synthesized answers with citations from real-time web search.
| Value | Environment Variable | Description |
|-------|---------------------|-------------|
| `secrets.perplexityApiKey` | `PERPLEXITY_API_KEY` | Perplexity API key |
```bash
helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set secrets.perplexityApiKey=<your-perplexity-api-key>
```
</details>
๐ [Web Search Documentation](https://docs.openclaw.ai/tools/web)
## Development
```bash
# Lint the chart
./scripts/helm-lint.sh
# Render templates with each values file
./scripts/helm-test.sh
# Ad-hoc template rendering
helm template openclaw . -f values.yaml
```
<details>
<summary>Publishing</summary>
Charts are published to GHCR as OCI artifacts on pushes to `main`.
Manual publish:
```bash
helm registry login ghcr.io -u <github-username> -p <github-token>
./scripts/publish-chart.sh
```
Environment overrides:
- `CHART_DIR`: chart directory (default: `.`)
- `CHART_OCI_REPO`: OCI repo (default: `ghcr.io/feiskyer/openclaw-kubernetes` based on `GITHUB_REPOSITORY`)
Bump `Chart.yaml` version before each release; OCI registries reject duplicate versions.
</details>
## FAQ
<details>
<summary>Telegram fails with ENETUNREACH or network errors</summary>
On dual-stack clusters (IPv4 + IPv6), Node 22+ enables Happy Eyeballs (`autoSelectFamily`) which tries IPv6 first. If IPv6 is configured but unreachable, connections to `api.telegram.org` fail with `ENETUNREACH` before IPv4 can connect.
The chart handles this automatically via two mechanisms:
1. `NODE_OPTIONS=--dns-result-order=ipv4first` in the container env
2. `channels.telegram.network.autoSelectFamily: false` in `openclaw.json`
If you use a custom `openclaw.json` (not chart-managed), add the network config manually:
```json
{
"channels": {
"telegram": {
"network": {
"autoSelectFamily": false
}
}
}
}
```
</details>
<details>
<summary>How to use a free model?</summary>
Run the onboard script and select **QWen** or **OpenCode Zen**, then pick a free model:
```bash
kubectl -n openclaw exec -it openclaw-0 -- node openclaw.mjs onboard
```
Example with OpenCode Zen:

</details>
<details>
<summary>How to join the Moltbook community?</summary>
Send this prompt to your OpenClaw agent:
```
Read https://moltbook.com/skill.md and follow the instructions to join Moltbook
```
</details>
<details>
<summary>How to modify configuration after deployment?</summary>
Run the onboard command:
```bash
kubectl -n openclaw exec -it openclaw-0 -- node openclaw.mjs onboard
```
</details>
<details>
<summary>How to authorize Telegram or Slack users?</summary>
Set `openclaw.dmAccess.policy=allowlist` and provide user IDs via `--set-json`:
```bash
# Telegram: get your ID from @userinfobot
helm upgrade openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set openclaw.dmAccess.policy=allowlist \
--set-json 'openclaw.dmAccess.allowFrom.telegram=["tg:123456789"]'
# Slack: copy member ID from user profile (format: U053FP6RAMA)
helm upgrade openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
--set secrets.openclawGatewayToken=$gatewayToken \
--set openclaw.dmAccess.policy=allowlist \
--set-json 'openclaw.dmAccess.allowFrom.slack=["U053FP6RAMA"]'
```
Users in `allowFrom` bypass the pairing flow. Use `policy=pairing` (default) to keep pairing for everyone else while pre-approving specific users.
</details>
<details>
<summary>How to fix "disconnected (1008): pairing required" error?</summary>
List pending device requests and approve yours:
```bash
kubectl -n openclaw exec -it openclaw-0 -- node dist/index.js devices list
kubectl -n openclaw exec -it openclaw-0 -- node dist/index.js devices approve <your-request-id>
```
</details>
## Links
- [OpenClaw](https://openclaw.ai/) (formerly Moltbot/Clawdbot)
- [OpenClaw Documentation](https://docs.openclaw.ai/)
- [AI Agent Community](https://www.moltbook.com/)
- [Source Code](https://github.com/openclaw/openclaw)
## Acknowledgments
<details>
<summary>OpenClaw Project</summary>
This Helm chart deploys [OpenClaw](https://openclaw.ai/), an open-source personal AI assistant gateway. Thanks to the OpenClaw team for building and maintaining this project.
- [OpenClaw Website](https://openclaw.ai/)
- [OpenClaw Documentation](https://docs.openclaw.ai/)
- [OpenClaw Source Code](https://github.com/openclaw/openclaw)
</details>
<details>
<summary>Official Kubernetes Guide</summary>
For a non-Helm approach to deploying OpenClaw on Kubernetes, see the [official Kubernetes guide](http://docs.openclaw.ai/install/kubernetes).
</details>
## License
This project is licensed under the [MIT License](LICENSE).