openclaw-operator

OpenClaw Kubernetes Operator

Self-host OpenClaw AI agents on Kubernetes with production-grade security, observability, and lifecycle management.

OpenClaw is an AI agent platform that acts on your behalf across Telegram, Discord, WhatsApp, and Signal. It manages your inbox, calendar, smart home, and more through 50+ integrations. While Paperclip Inc. offers fully managed hosting, this operator lets you run OpenClaw on your own infrastructure with the same operational rigor.

Why an Operator?

Deploying AI agents to Kubernetes involves more than a Deployment and a Service. You need network isolation, secret management, persistent storage, health monitoring, optional browser automation, and config rollouts, all wired correctly. This operator encodes those concerns into a single OpenClawInstance custom resource so you can go from zero to production in minutes:

apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-agent
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys
  storage:
    persistence:
      enabled: true
      size: 10Gi

The operator reconciles this into a fully managed stack of 9+ Kubernetes resources: secured, monitored, and self-healing.

Agents That Adapt Themselves

Agents can autonomously install skills, patch their config, add environment variables, and seed workspace files - all through the Kubernetes API, validated by the operator on every request.

# 1. Enable self-configure on the instance
spec:
  selfConfigure:
    enabled: true
    allowedActions: [skills, config, envVars, workspaceFiles]

# 2. The agent creates this to install a skill at runtime
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawSelfConfig
metadata:
  name: add-fetch-skill
spec:
  instanceRef: my-agent
  addSkills:
    - "@anthropic/mcp-server-fetch"

Every request is validated against the instance's allowlist policy. Protected config keys cannot be overwritten, and denied requests are logged with a reason. See Self-configure for details.

Note: Without selfConfigure enabled, config or skill changes made by the agent inside the container won't trigger a pod restart. You'll need to restart the pod manually (e.g. kubectl delete pod ) for changes to take effect.

Features

Architecture

…

Quick Start

Prerequisites

• Kubernetes 1.28+
• Helm 3

1. Install the operator

helm install openclaw-operator \
  oci://ghcr.io/paperclipinc/charts/openclaw-operator \
  --namespace openclaw-operator-system \
  --create-namespace

Alternative: install with Kustomize

# Install CRDs
make install

# Deploy the operator
make deploy IMG=ghcr.io/paperclipinc/openclaw-operator:latest

Restrict the operator to specific namespaces

To run the operator with namespaced RBAC instead of cluster-wide permissions, list the namespaces it should watch. The chart switches the namespace-scoped permissions from a ClusterRole/ClusterRoleBinding to per-namespace Role/RoleBinding, and passes --watch-namespaces to the operator so its informer cache is scoped to that list. The operator's own namespace is added to the Secret informer only, so it can still read its backup credentials, and the chart renders a matching Secret-only Role there; no other resource type is watched or granted in the operator namespace. A ClusterRole/ClusterRoleBinding is still created for the cluster-scoped OpenClawClusterDefaults resource, which the operator watches regardless of namespace scoping -- a namespaced Role cannot grant access to a cluster-scoped resource.

helm install openclaw-operator \
  oci://ghcr.io/paperclipinc/charts/openclaw-operator \
  --namespace openclaw-operator-system \
  --create-namespace \
  --set 'watchNamespaces={team-a,team-b}'

Each listed namespace must already exist; the chart does not create them.

To bring your own RBAC entirely (e.g. managed by a separate controller or SecurityCenter policy), disable chart-managed RBAC:

helm install openclaw-operator \
  oci://ghcr.io/paperclipinc/charts/openclaw-operator \
  --namespace openclaw-operator-system \
  --create-namespace \
  --set rbac.create=false

The kubebuilder markers in internal/controller/ and the manager rules helper at charts/openclaw-operator/templates/_helpers.tpl document the minimum permission set the operator requires.

2. Create a secret with your API keys

apiVersion: v1
kind: Secret
metadata:
  name: openclaw-api-keys
type: Opaque
stringData:
  ANTHROPIC_API_KEY: "sk-ant-..."

3. Deploy an OpenClaw instance

apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-agent
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys
  storage:
    persistence:
      enabled: true
      size: 10Gi

kubectl apply -f secret.yaml -f openclawinstance.yaml

4. Verify

kubectl get openclawinstances
# NAME       PHASE     AGE
# my-agent   Running   2m

kubectl get pods
# NAME         READY   STATUS    AGE
# my-agent-0   1/1     Running   2m

Configuration

Inline config (openclaw.json)

spec:
  config:
    raw:
      agents:
        defaults:
          model:
            primary: "anthropic/claude-sonnet-4-20250514"
          sandbox: true
      session:
        scope: "per-sender"

External ConfigMap reference

spec:
  config:
    configMapRef:
      name: my-openclaw-config
      key: openclaw.json

Config changes are detected via SHA-256 hashing and automatically trigger a rolling update. No manual restart needed.

Gateway proxy

By default, each pod includes an nginx reverse proxy sidecar that forwards traffic to the OpenClaw gateway on loopback. Set spec.gateway.enabled: false to disable it:

spec:
  gateway:
    image:
      repository: docker.io/library/nginx
      tag: 1.27-alpine
      # digest: sha256:...  # takes precedence over tag
    resources:
      requests:
        cpu: 10m
        memory: 16Mi
      limits:
        cpu: 100m
        memory: 64Mi

The image and resource fields are optional. Omit them to retain the defaults above, or set an image digest to make the proxy supply-chain reference immutable.

• Health probes and Service ports target the gateway directly on port 18789
• gateway.bind is set to 0.0.0.0 instead of loopback
• The gateway-proxy container and its tmp volume are omitted from the pod
• To replace the built-in proxy with your own (e.g., Envoy, a signing proxy), disable it and add your proxy via spec.sidecars
• Warning: Do not set gateway.bind: loopback in your config JSON when the proxy is disabled - the gateway will only listen on 127.0.0.1 with nothing forwarding external traffic, making the pod unreachable. The operator emits a GatewayBindConflict warning event if this misconfiguration is detected.
• TLS: When the proxy is disabled, the gateway serves plaintext ws:// on 0.0.0.0. Ensure your replacement proxy or Ingress handles TLS termination to avoid exposing unencrypted WebSocket traffic (CWE-319).

Disk-aware readiness

By default the readiness probe is an HTTP GET /readyz against the gateway. For PVC-backed instances, /readyz can stay green while the workspace volume is full or read-only (ENOSPC), so the pod keeps receiving traffic while workspace