### Full GitOps Example with Multiple Agents and Kustomize

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

A comprehensive Kustomize configuration for a multi-agent setup, defining separate ConfigMaps for the main agent and the scheduler agent's workspaces. This example includes the `instance.yaml` resource and specifies files for each agent's workspace.

```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: my-namespace

generatorOptions:
  disableNameSuffixHash: true

resources:
  - instance.yaml

configMapGenerator:
  - name: main-agent-workspace
    files:
      - agents/main/SOUL.md
      - agents/main/AGENT.md
  - name: scheduler-workspace
    files:
      - agents/scheduler/SOUL.md
      - agents/scheduler/TOOLS.md
```

--------------------------------

### Plugin Installation

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Declarative installation of plugins using their npm package names. The operator's init container handles installation before the agent starts.

```yaml
spec:
  plugins:
    - "@martian-engineering/lossless-claw"
    - "some-other-plugin"
```

--------------------------------

### OpenClawSelfConfig Example

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/openclaw-self-config.md

This example demonstrates how to create an OpenClawSelfConfig resource to add a new skill and an environment variable to an OpenClawInstance.

```yaml
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawSelfConfig
metadata:
  name: add-fetch-skill
spec:
  instanceRef: my-agent
  addSkills:
    - "mcp-server-fetch"
  addEnvVars:
    - name: MY_CUSTOM_VAR
      value: "hello"
```

--------------------------------

### Install Skills Declaratively

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Declare skills to be installed by the operator. Skills are fetched from ClawHub by default, or from npmjs.com when prefixed with `npm:`. Installation is idempotent.

```yaml
spec:
  skills:
    - "@anthropic/mcp-server-fetch"       # ClawHub (default)
    - "npm:@openclaw/matrix"              # npm package from npmjs.com
```

--------------------------------

### Skill Pack Reference (Raw-Repo Mode)

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Example of referencing a skill pack in raw-repo mode. The entire directory is installed verbatim when no `skillpack.json` is present.

```yaml
spec:
  skills:
    - "pack:fluxcd/agent-skills/skills/gitops-repo-audit@main"
    # installs every file under skills/gitops-repo-audit/ into the workspace
    # at skills/gitops-repo-audit/ (including nested assets, schemas, etc.)
```

--------------------------------

### Create Kind Cluster and Install CRDs

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CONTRIBUTING.md

Set up a local Kubernetes cluster using Kind and install the Custom Resource Definitions.

```bash
kind create cluster

make install
```

--------------------------------

### Agent Installs Skill at Runtime

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

An agent uses this OpenClawSelfConfig resource to request the installation of a skill during runtime. The `instanceRef` points to the agent that requires the skill.

```yaml
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawSelfConfig
metadata:
  name: add-fetch-skill
spec:
  instanceRef: my-agent
  addSkills:
    - "@anthropic/mcp-server-fetch"
```

--------------------------------

### Install Openclaw Operator using Kustomize

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Install the operator by cloning the repository, installing CRDs, and deploying the operator.

```bash
# Clone the repository
git clone https://github.com/paperclipinc/openclaw-operator.git
cd openclaw-operator

# Install CRDs
make install

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

--------------------------------

### Clone and Setup Project

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CONTRIBUTING.md

Clone the repository, set up the upstream remote, and download project dependencies.

```bash
git clone https://github.com/YOUR_USERNAME/openclaw-operator.git
cd openclaw-operator

git remote add upstream https://github.com/paperclipinc/openclaw-operator.git

go mod download
```

--------------------------------

### Run Locally with Kind

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Set up a local Kubernetes cluster with Kind, install the operator, and run it.

```bash
kind create cluster
make install
make run
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs-site/README.md

Starts a local server for previewing the documentation. Open the provided URL in your browser to view the site.

```bash
make docs-serve
# open http://127.0.0.1:8000
```

--------------------------------

### Install nginx-ingress Controller

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Install the nginx-ingress controller using Helm. This is an optional step for enabling WebSocket support and exposing the instance via Ingress.

```bash
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx --create-namespace
```

--------------------------------

### Create OpenClaw Instance Test Setup

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Creates a namespace, a secret for API keys, and applies an OpenClawInstance custom resource for testing.

```bash
kubectl create namespace openclaw

kubectl create secret generic openclaw-api-keys \
  --namespace openclaw \
  --from-literal=ANTHROPIC_API_KEY=sk-your-key

kubectl apply -f - <<EOF
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: dev-assistant
  namespace: openclaw
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys
  storage:
    persistence:
      enabled: false
EOF
```

--------------------------------

### Install Openclaw Operator using Helm

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Install the operator using Helm by adding the OCI registry and performing the installation.

```bash
# Add the OCI registry (no separate repo add needed for OCI)
helm install openclaw-operator \
  oci://ghcr.io/paperclipinc/charts/openclaw-operator \
  --namespace openclaw-system --create-namespace \
  --set leaderElection.enabled=true
```

--------------------------------

### Install Amazon EBS CSI Driver and StorageClass

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Install the Amazon EBS CSI driver for persistent storage. A `gp3` StorageClass is recommended for optimal performance and cost-efficiency.

```bash
eksctl create addon --name aws-ebs-csi-driver --cluster openclaw-cluster
```

```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer
parameters:
  type: gp3
  encrypted: "true"
```

--------------------------------

### OpenClawClusterDefaults Example

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/openclaw-cluster-defaults.md

This is an example of the OpenClawClusterDefaults CR. The name must be 'cluster' for it to be applied.

```yaml
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawClusterDefaults
metadata:
  name: cluster
spec:
  registry: "<account>.dkr.ecr.<region>.amazonaws.com.cn"
  image:
    tag: v0.28.0
  env:
    - name: NPM_CONFIG_REGISTRY
      value: https://registry.npmmirror.com
    - name: PIP_INDEX_URL
      value: https://mirrors.aliyun.com/pypi/simple/
  runtimeDeps:
    python: true
```

--------------------------------

### Install nginx-ingress Controller

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Install the nginx-ingress controller using Helm. This command configures the controller's health probe request path, which is necessary for exposing services.

```bash
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx --create-namespace \
  --set controller.service.annotations."service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path"=/healthz
```

--------------------------------

### OpenClawInstance CR Example

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/model-fallback.md

Example of an OpenClawInstance Custom Resource that uses `envFrom` to inject environment variables from a Secret.

```yaml
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-assistant
spec:
  envFrom:
    - secretRef:
        name: ai-provider-keys
```

--------------------------------

### Enable Runtime Dependencies for Agent

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Enable built-in init containers to install pnpm or Python with uv into the data PVC. This is useful for MCP servers and skills that require these runtimes.

```yaml
spec:
  runtimeDeps:
    pnpm: true    # Installs pnpm via corepack
    python: true  # Installs Python 3.12 + uv
```

--------------------------------

### Get Helm Release Details

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/charts/openclaw-operator/templates/NOTES.txt

Retrieve all details for a Helm release.

```bash
helm get all {{ .Release.Name }}
```

--------------------------------

### Install OpenClaw Operator with Helm

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Installs the OpenClaw operator using Helm. Ensure Kubernetes 1.28+ and Helm 3 are prerequisites.

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

--------------------------------

### Verify Kubernetes Cluster Readiness

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Check the status of your Kubernetes cluster components before installation.

```bash
kubectl version
kubectl get nodes
kubectl get storageclass
```

--------------------------------

### Create OpenClawInstance Resource

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/charts/openclaw-operator/templates/NOTES.txt

Define and apply an OpenClawInstance custom resource. This example configures environment variables from a secret and enables persistent storage.

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

--------------------------------

### Create OpenClawInstance and API Key Secret

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Create an `OpenClawInstance` resource and store API keys in a Kubernetes Secret. This example configures resources, storage, and networking for the instance.

```bash
kubectl create namespace openclaw

# Store API keys in a Secret
kubectl create secret generic openclaw-api-keys \
  --namespace openclaw \
  --from-literal=ANTHROPIC_API_KEY=sk-your-key
```

```yaml
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-assistant
  namespace: openclaw
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys
  resources:
    requests:
      cpu: "1"
      memory: 2Gi
    limits:
      cpu: "2"
      memory: 4Gi
  storage:
    persistence:
      enabled: true
      storageClass: gp3
      size: 50Gi
  networking:
    service:
      type: ClusterIP
```

--------------------------------

### Skill Pack References

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Examples of how to reference skill packs in YAML configuration. Supports latest, pinned versions, and private repositories.

```yaml
spec:
  skills:
    - "pack:paperclipinc/skills/image-gen"            # latest from default branch
    - "pack:paperclipinc/skills/image-gen@v1.0.0"     # pinned to tag
    - "pack:myorg/private-skills/custom-tool@main"       # private repo (requires GITHUB_TOKEN)
```

--------------------------------

### Check CRD Installation

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/troubleshooting.md

Verify if the Custom Resource Definition (CRD) for OpenclawInstances is installed and up-to-date. If missing or outdated, apply the correct CRDs.

```bash
# Check if CRD exists
kubectl get crd openclawinstances.openclaw.rocks

# Install CRD if missing
kubectl apply -f config/crd/bases/

# Apply CRDs with server-side apply (for upgrades)
kubectl apply --server-side -f config/crd/bases/
```

--------------------------------

### Backup Path Format Example

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/backup-restore.md

Illustrates the S3 backup path structure, including placeholders for tenant ID, instance name, and timestamp. The last successful backup path is stored in status.lastBackupPath.

```text
s3://<bucket>/backups/<tenantId>/<instanceName>/<timestamp>
```

--------------------------------

### Install OpenClaw Operator with Helm

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Deploy the OpenClaw Operator to the `openclaw-system` namespace using Helm. Leader election is enabled by default.

```bash
helm install openclaw-operator \
  oci://ghcr.io/paperclipinc/charts/openclaw-operator \
  --namespace openclaw-system --create-namespace \
  --set leaderElection.enabled=true
```

--------------------------------

### Configure Backup Timeout

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/backup-restore.md

Example of configuring the backup timeout for pre-delete backups. The timeout can be set via spec.backup.timeout, with a default of 30 minutes, a minimum of 5 minutes, and a maximum of 24 hours.

```yaml
spec:
  backup:
    timeout: "1h"  # Allow up to 1 hour for pre-delete backups (default: 30m, min: 5m, max: 24h)
```

--------------------------------

### Configure OpenClaw Instance for Ingress

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Update the OpenClaw instance configuration to enable Ingress, specify the ingress class, hosts, and TLS settings. This example assumes an nginx ingress controller and a pre-existing TLS secret.

```yaml
spec:
  networking:
    ingress:
      enabled: true
      className: nginx
      hosts:
        - host: openclaw.example.com
          paths:
            - path: /
      tls:
        - hosts:
            - openclaw.example.com
          secretName: openclaw-tls
  security:
    networkPolicy:
      allowedIngressNamespaces:
        - ingress-nginx
```

--------------------------------

### Check Instance Backup Phase Status

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/troubleshooting.md

Query the current phase and backup start time of an OpenclawInstance. This is useful for diagnosing instances stuck in the 'BackingUp' phase.

```bash
kubectl get openclawinstance my-agent -o jsonpath='{.status.phase}'
```

```bash
kubectl get openclawinstance my-agent -o jsonpath='{.status.backingUpSince}'
```

--------------------------------

### Verify CRD Installation

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/troubleshooting.md

Confirm that the necessary Custom Resource Definition (CRD) for OpenClaw instances is installed. The controller may fail to start if this CRD is missing.

```bash
kubectl get crd openclawinstances.openclaw.rocks
```

--------------------------------

### Get Managed Resources for an Instance

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/troubleshooting.md

Retrieve the list of managed resources associated with a specific OpenClaw instance. Requires jq to be installed.

```bash
# Get managed resources for an instance
kubectl get openclawinstance my-assistant -n openclaw \
  -o jsonpath='{.status.managedResources}' | jq .
```

--------------------------------

### Clone and Set Up Openclaw Operator

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Clone the repository, navigate to the directory, and download Go module dependencies.

```bash
git clone https://github.com/paperclipinc/openclaw-operator.git
cd openclaw-operator
go mod download
```

--------------------------------

### Run GolangCI-Lint

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CLAUDE.md

Perform static analysis on the Go code using golangci-lint.

```bash
make lint
```

--------------------------------

### Install OpenClaw Operator with Disabled RBAC Creation

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Installs the operator while disabling chart-managed RBAC creation. This is useful if you manage RBAC separately.

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

--------------------------------

### Run Go Vet Check

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CLAUDE.md

Perform static analysis using the Go vet tool.

```bash
go vet ./...
```

--------------------------------

### Build and Load Docker Image

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CONTRIBUTING.md

Build a Docker image for the operator and load it into the Kind cluster.

```bash
make docker-build IMG=my-operator:dev

kind load docker-image my-operator:dev
```

--------------------------------

### Post-Installation Verification Checks

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Perform comprehensive checks after deployment to ensure all components are functioning correctly.

```bash
# 1. Operator is running
kubectl get pods -n openclaw-system
# Expected: 1/1 Running

# 2. CRD is installed
kubectl get crd openclawinstances.openclaw.rocks
# Expected: CRD listed with creation date

# 3. Instance reaches Running phase
kubectl get openclawinstance -n openclaw
# Expected: Phase=Running, Ready=True

# 4. All managed resources exist
kubectl get deploy,svc,sa,role,rolebinding,networkpolicy,pdb -n openclaw \
  -l app.kubernetes.io/managed-by=openclaw-operator

# 5. Pod is healthy
kubectl get pods -n openclaw -l app.kubernetes.io/name=openclaw
# Expected: 1/1 Running (or 2/2 with Chromium sidecar)

# 6. Gateway is reachable (from within the cluster)
kubectl run -n openclaw test-curl --rm -it --image=curlimages/curl -- \
  curl -s -o /dev/null -w '%{http_code}' http://my-assistant:18789
```

--------------------------------

### Create Openclaw Instance with API Key Secret

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Create a namespace, a secret for API keys, and apply an OpenClawInstance resource.

```bash
kubectl create namespace openclaw

kubectl create secret generic openclaw-api-keys \
  --namespace openclaw \
  --from-literal=ANTHROPIC_API_KEY=sk-your-key

kubectl apply -f - <<EOF
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-assistant
  namespace: openclaw
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys
EOF
```

--------------------------------

### Install OpenClaw Operator with Namespaced RBAC

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Installs the operator with namespaced RBAC, restricting it to watch specific namespaces. The chart creates per-namespace Role/RoleBinding and passes '--watch-namespaces' to the operator. Ensure the specified namespaces exist.

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

--------------------------------

### Get Helm Release Status

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/charts/openclaw-operator/templates/NOTES.txt

Retrieve the status of a Helm release.

```bash
helm status {{ .Release.Name }}
```

--------------------------------

### Install CRDs

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CLAUDE.md

Apply the Custom Resource Definitions to the current Kubernetes cluster.

```bash
make install
```

--------------------------------

### Run Operator Locally

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CONTRIBUTING.md

Start the OpenClaw operator locally for development and debugging.

```bash
make run
```

--------------------------------

### Build and Load Operator Image for Kind

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Builds the operator Docker image and loads it into the specified Kind cluster.

```bash
# Build the image
make docker-build IMG=openclaw-operator:dev

# Load into Kind
kind load docker-image openclaw-operator:dev --name openclaw-dev
```

--------------------------------

### Get PVC Size

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/runbooks/OpenClawPVCNearlyFull.md

Retrieves the size and status of the PersistentVolumeClaim associated with the OpenClaw instance.

```bash
kubectl get pvc -n <namespace> -l app.kubernetes.io/instance=<name>

```

--------------------------------

### Full OpenClawInstance YAML Configuration

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/full-example.md

This snippet demonstrates a complete OpenClawInstance YAML configuration. It includes settings for image, configuration, workspace, skills, environment variables, self-configuration, resource requests and limits, security contexts, network policies, RBAC, CA bundles, storage, Chromium integration, Ollama integration, networking (service, ingress, TLS, rate limiting), probes, observability (metrics, logging), availability (PDB, node selectors, tolerations, affinity), runtime dependencies, gateway integration, and auto-update.

```yaml
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-assistant
  namespace: openclaw
spec:
  image:
    repository: ghcr.io/openclaw/openclaw
    tag: "0.5.0"
    pullPolicy: IfNotPresent
    pullSecrets:
      - name: ghcr-secret

  config:
    mergeMode: merge
    raw:
      mcpServers:
        filesystem:
          command: npx
          args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]

  workspace:
    initialDirectories:
      - tools/scripts
    initialFiles:
      CLAUDE.md: |
        # Project Instructions
        Use the filesystem MCP server for file operations.

  skills:
    - "mcp-server-fetch"
    - "npm:@openclaw/matrix"

  envFrom:
    - secretRef:
        name: openclaw-api-keys

  selfConfigure:
    enabled: true
    allowedActions:
      - skills
      - config

  resources:
    requests:
      cpu: "1"
      memory: 2Gi
    limits:
      cpu: "4"
      memory: 8Gi

  security:
    podSecurityContext:
      runAsUser: 1000
      runAsGroup: 1000
      fsGroup: 1000
      fsGroupChangePolicy: OnRootMismatch
      runAsNonRoot: true
    containerSecurityContext:
      allowPrivilegeEscalation: false
    networkPolicy:
      enabled: true
      allowedIngressNamespaces:
        - monitoring
      allowDNS: true
      additionalEgress:
        - to:
            - namespaceSelector:
                matchLabels:
                  app: postgres
          ports:
            - protocol: TCP
              port: 5432
    rbac:
      createServiceAccount: true
      serviceAccountAnnotations:
        eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/openclaw-role
    caBundle:
      configMapName: corporate-ca
      key: ca-bundle.crt

  storage:
    persistence:
      enabled: true
      storageClass: gp3
      size: 50Gi
      accessModes:
        - ReadWriteOnce

  chromium:
    enabled: true
    image:
      repository: chromedp/headless-shell
      tag: "stable"
    resources:
      requests:
        cpu: 500m
        memory: 1Gi
      limits:
        cpu: "2"
        memory: 4Gi
    persistence:
      enabled: true
      size: 2Gi

  ollama:
    enabled: true
    models:
      - llama3.2
      - nomic-embed-text
    resources:
      requests:
        cpu: "2"
        memory: 4Gi
      limits:
        cpu: "8"
        memory: 16Gi
    storage:
      sizeLimit: 40Gi
    gpu: 1

  networking:
    service:
      type: ClusterIP
    ingress:
      enabled: true
      className: nginx
      hosts:
        - host: openclaw.example.com
          paths:
            - path: "/"
              pathType: Prefix
      tls:
        - hosts:
            - openclaw.example.com
          secretName: openclaw-tls
      security:
        forceHTTPS: true
        enableHSTS: true
        rateLimiting:
          enabled: true
          requestsPerSecond: 20

  probes:
    liveness:
      enabled: true
      initialDelaySeconds: 60
      periodSeconds: 15
    readiness:
      enabled: true
      initialDelaySeconds: 10
    startup:
      enabled: true
      failureThreshold: 60

  observability:
    metrics:
      enabled: true
      serviceMonitor:
        enabled: true
        interval: 15s
        labels:
          release: prometheus
    logging:
      level: info
      format: json

  availability:
    podDisruptionBudget:
      enabled: true
      maxUnavailable: 1
    nodeSelector:
      node-type: compute
    tolerations:
      - key: dedicated
        operator: Equal
        value: openclaw
        effect: NoSchedule
    affinity:
      podAntiAffinity:
        preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              topologyKey: kubernetes.io/hostname
              labelSelector:
                matchLabels:
                  app.kubernetes.io/name: openclaw

  runtimeDeps:
    pnpm: true
    python: true

  gateway:
    existingSecret: my-gateway-token

  autoUpdate:
    enabled: true
    checkInterval: 12h
    backupBeforeUpdate: true
    rollbackOnFailure: true
    healthCheckTimeout: 15m

```

--------------------------------

### Check PVC Status

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/troubleshooting.md

Use kubectl to get and describe PersistentVolumeClaims to diagnose binding issues.

```bash
kubectl get pvc -n openclaw
kubectl describe pvc my-assistant-data -n openclaw
```

--------------------------------

### OpenClawInstance Status Phase Transitions

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/architecture.md

Illustrates the lifecycle flow of an OpenClawInstance through various phases, including normal operation, degradation, failure, and deletion.

```text
Pending --> Provisioning --> Running
        |               |
        v               v
     Failed         Degraded (e.g., skill packs unavailable)
        |
        v
   (retry)          (retry --> Running when resolved)

Deletion from any phase:
  * --> Terminating --> (removed)
```

--------------------------------

### Run Tests and Linter

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CONTRIBUTING.md

Execute the test suite and run the linter to ensure code quality.

```bash
make test

make lint
```

--------------------------------

### Configure NetworkPolicy for Ingress

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/troubleshooting.md

Example of NetworkPolicy configuration to allow traffic from the Ingress controller's namespace.

```yaml
spec:
  security:
    networkPolicy:
      allowedIngressNamespaces:
        - ingress-nginx
```

--------------------------------

### Generate Code and Manifests

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CONTRIBUTING.md

Generate necessary code and Kubernetes manifests for the operator.

```bash
make generate manifests
```

--------------------------------

### Get GKE Cluster Credentials

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Configure kubectl to connect to the newly created or existing GKE cluster.

```bash
# Get credentials
gcloud container clusters get-credentials openclaw-cluster --zone us-central1-a
```

--------------------------------

### Azure Workload Identity Configuration

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/external-secrets.md

Example of configuring Azure Workload Identity using serviceAccountAnnotations for workload identity.

```yaml
spec:
  security:
    rbac:
      serviceAccountAnnotations:
        azure.workload.identity/client-id: "00000000-0000-0000-0000-000000000000"
```

--------------------------------

### GCP Workload Identity Configuration

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/external-secrets.md

Example of configuring GCP Workload Identity using serviceAccountAnnotations for workload identity.

```yaml
spec:
  security:
    rbac:
      serviceAccountAnnotations:
        iam.gke.io/gcp-service-account: "openclaw@my-project.iam.gserviceaccount.com"
```

--------------------------------

### Create OpenClawInstance with API Keys and Storage

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Create an OpenClawInstance in the 'openclaw' namespace, referencing a secret for API keys and configuring persistent storage with a specified StorageClass and size. The instance uses ClusterIP for networking.

```yaml
kubectl create namespace openclaw
kubectl create secret generic openclaw-api-keys \
  --namespace openclaw \
  --from-literal=ANTHROPIC_API_KEY=sk-your-key
kubectl apply -f - <<EOF
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-assistant
  namespace: openclaw
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys
  storage:
    persistence:
      enabled: true
      storageClass: managed-csi
      size: 50Gi
  networking:
    service:
      type: ClusterIP
EOF
```

--------------------------------

### PostHog Initialization Script

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs-site/overrides/partials/integrations/analytics.html

Initializes PostHog analytics with your API key and host. Ensure your PostHog API key is configured in `config.extra.analytics_keys.posthog`.

```javascript
{% if config.extra.analytics_keys and config.extra.analytics_keys.posthog %} !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js";(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]); posthog.init('{{ config.extra.analytics_keys.posthog }}', {api_host:'https://eu.i.posthog.com'}); {% endif %}
```

--------------------------------

### RuntimeDepsSpec

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/api-reference.md

RuntimeDepsSpec configures built-in init containers that install runtime dependencies to the data PVC for use by MCP servers and skills.

```APIDOC
## RuntimeDepsSpec

### Description
RuntimeDepsSpec configures built-in init containers to install runtime dependencies to the data PVC, making them available for MCP servers and skills.

### Fields

- **pnpm** (boolean) - Pnpm installs pnpm via corepack for npm-based MCP servers and skills.
- **python** (boolean) - Python installs Python 3.12 and uv for Python-based MCP servers and skills.
```

--------------------------------

### Deploy Operator using Helm

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Installs the OpenClaw Operator using Helm, specifying the namespace, image details, and pull policy.

```bash
helm install openclaw-operator charts/openclaw-operator \
  --namespace openclaw-system --create-namespace \
  --set image.repository=openclaw-operator \
  --set image.tag=dev \
  --set image.pullPolicy=Never
```

--------------------------------

### Check Instance Failure Reason

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/troubleshooting.md

Retrieve the specific message associated with the 'Ready' condition to understand why an instance entered the 'Failed' state. This provides a concise reason for the failure.

```bash
kubectl get openclawinstance my-assistant -n openclaw \
  -o jsonpath='{.status.conditions[?(@.type=="Ready")].message}'
```

--------------------------------

### Add Custom Init Containers and Sidecars

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Configure custom init containers to run after operator-managed ones and add sidecar containers. Specify container details, commands, arguments, and volume mounts.

```yaml
spec:
  initContainers:
    - name: fetch-models
      image: curlimages/curl:8.5.0
      command: ["sh", "-c", "curl -o /data/model.bin https://..."]
      volumeMounts:
        - name: data
          mountPath: /data
  sidecars:
    - name: cloud-sql-proxy
      image: gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.14.3
      args: ["--structured-logs", "my-project:us-central1:my-db"]
      ports:
        - containerPort: 5432
  sidecarVolumes:
    - name: proxy-creds
      secret:
        secretName: cloud-sql-proxy-sa
```

--------------------------------

### AWS IRSA Configuration

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/external-secrets.md

Example of configuring AWS IAM Roles for Service Accounts (IRSA) using serviceAccountAnnotations for workload identity.

```yaml
spec:
  security:
    rbac:
      serviceAccountAnnotations:
        eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/openclaw-role"
```

--------------------------------

### Create OpenClaw Instance with API Key Secret

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Deploy an OpenClaw instance, including creating a Kubernetes secret for API keys and configuring storage and networking.

```bash
kubectl create namespace openclaw

kubectl create secret generic openclaw-api-keys \
  --namespace openclaw \
  --from-literal=ANTHROPIC_API_KEY=sk-your-key

kubectl apply -f - <<EOF
apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-assistant
  namespace: openclaw
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys
  storage:
    persistence:
      enabled: true
      size: 50Gi
  networking:
    service:
      type: ClusterIP
EOF
```

--------------------------------

### Deploy Operator to Kind

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CONTRIBUTING.md

Deploy the operator's Docker image to the Kind cluster.

```bash
make deploy IMG=my-operator:dev
```

--------------------------------

### Describe OpenClaw Instance for Auto-Update Events

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/runbooks/OpenClawAutoUpdateRollback.md

Get detailed information about an OpenClaw instance, filtering for events related to auto-updates. This can provide context for failures.

```bash
kubectl describe openclawinstance <name> -n <namespace> | grep -A5 AutoUpdate
```

--------------------------------

### Create Kind Cluster

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Creates a local Kubernetes cluster named 'openclaw-dev' using Kind.

```bash
kind create cluster --name openclaw-dev
```

--------------------------------

### Enable ServiceMonitor for Prometheus Metrics

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Configure the ServiceMonitor to enable Prometheus to scrape metrics from the OpenClaw operator. Ensure the labels match your Prometheus setup.

```yaml
spec:
  observability:
    metrics:
      enabled: true
      serviceMonitor:
        enabled: true
        interval: 15s
        labels:
          release: prometheus
```

--------------------------------

### Kubernetes Secret for AI Provider Keys

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/model-fallback.md

Example of a Kubernetes Secret containing API keys for multiple AI providers. Ensure this Secret is referenced in your OpenClawInstance.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: ai-provider-keys
type: Opaque
stringData:
  ANTHROPIC_API_KEY: "sk-ant-..."
  OPENAI_API_KEY: "sk-..."
  GOOGLE_AI_API_KEY: "AIza..."
```

--------------------------------

### Check Ingress Controller Pods

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/troubleshooting.md

Verify that the Ingress controller pods (e.g., nginx-ingress) are running.

```bash
kubectl get pods -n ingress-nginx
```

--------------------------------

### Scaffold v1 API

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/superpowers/plans/2026-06-03-v1-graduation-plan.md

Scaffolds the api/v1 directory by mirroring the api/v1alpha1 structure. This command is used to create the initial v1 API resources.

```bash
operator-sdk create api --group openclaw --version v1 --kind OpenClawInstance
```

--------------------------------

### Verify OpenClaw Instance and Pods

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Verifies the deployment by checking the status of OpenClawInstances and associated pods using kubectl commands.

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

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

--------------------------------

### Skill Pack Manifest (Manifest Mode)

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

A JSON manifest defining files and configuration to be seeded from a skill pack. Used in explicit mode for precise control over installation.

```json
{
  "files": {
    "skills/image-gen/SKILL.md": "SKILL.md",
    "skills/image-gen/scripts/generate.py": "scripts/generate.py"
  },
  "directories": ["skills/image-gen/scripts"],
  "config": {
    "image-gen": {"enabled": true}
  }
}
```

--------------------------------

### Run Unit and Integration Tests

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/CLAUDE.md

Execute unit and integration tests for the operator. Requires envtest binaries to be present.

```bash
make test
```

--------------------------------

### Check StatefulSet Progress

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/runbooks/OpenClawInstanceDegraded.md

Inspect the StatefulSet managing the OpenClaw instance to ensure it is progressing correctly and not encountering issues with pod management.

```bash
kubectl get statefulset <name> -n <namespace> -o yaml
```

--------------------------------

### Verify OpenClaw Deployment

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/docs/deployment.md

Check the status of the OpenClawInstance, pods, and services in the `openclaw` namespace to ensure the deployment was successful.

```bash
kubectl get openclawinstance -n openclaw
kubectl get pods -n openclaw
kubectl get svc -n openclaw
```

--------------------------------

### Reuse Existing Persistent Volume Claim

Source: https://github.com/paperclipinc/openclaw-operator/blob/main/README.md

Configure an agent to use an existing Persistent Volume Claim (PVC), for example, after restoring from a backup. This is useful for re-attaching retained storage.

```yaml
spec:
  storage:
    persistence:
      existingClaim: my-agent-data
```