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:

• 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 via Tailscale Serve: Enable tailscale.serve.enabled to get automatic HTTPS certificates from Tailscale for the gateway.

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 and examples/external-skills-pvc.yaml.

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

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

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:

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.

• 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

Set the model provider via litellm.secrets:

For providers with custom endpoints, set litellm.secrets.apiBase to the base URL.

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

To override the built-in config entirely, set litellm.configOverride with your complete LiteLLM YAML config.

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

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:

   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:

   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

• 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)

helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
  --set secrets.openclawGatewayToken=$gatewayToken \
  --set secrets.discordBotToken=<your-discord-bot-token>

📖 Discord Setup Guide

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:

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:

# 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

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

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

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

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

Structured results (title, URL, snippet) with a free tier available.

helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
  --set secrets.openclawGatewayToken=$gatewayToken \
  --set secrets.braveApiKey=<your-brave-api-key>

AI-synthesized answers with citations from real-time web search.

helm install openclaw oci://ghcr.io/feiskyer/openclaw-kubernetes/openclaw \
  --set secrets.openclawGatewayToken=$gatewayToken \
  --set secrets.perplexityApiKey=<your-perplexity-api-key>

Charts are published to GHCR as OCI artifacts on pushes to main.

Manual publish:

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.

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:

{
  "channels": {
    "telegram": {
      "network": {
        "autoSelectFamily": false
      }
    }
  }
}

Run the onboard script and select QWen or OpenCode Zen, then pick a free model:

kubectl -n openclaw exec -it openclaw-0 -- node openclaw.mjs onboard

Example with OpenCode Zen:

Send this prompt to your OpenClaw agent:

Read https://moltbook.com/skill.md and follow the instructions to join Moltbook

Run the onboard command:

kubectl -n openclaw exec -it openclaw-0 -- node openclaw.mjs onboard

Set openclaw.dmAccess.policy=allowlist and provide user IDs via --set-json:

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

List pending device requests and approve yours:

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>

This Helm chart deploys OpenClaw, an open-source personal AI assistant gateway. Thanks to the OpenClaw team for building and maintaining this project.

• OpenClaw Website
• OpenClaw Documentation
• OpenClaw Source Code

For a non-Helm approach to deploying OpenClaw on Kubernetes, see the official Kubernetes guide.