openclaw-operator: Running OpenClaw Agents as a Kubernetes Custom Resource
Kubernetes operator for deploying and managing OpenClaw AI agent instances with production-grade security, observability, and lifecycle management.
At a glance
- What is it?
- A Go operator that turns one OpenClawInstance object into a StatefulSet, NetworkPolicy, PVC, PDB and more. It is a good fit for platform teams self-hosting OpenClaw; the self-configure mechanism and the merge/forcePaths interaction are where the sharp edges sit.
- Who is it for?
- Adopt openclaw-operator if you already run Kubernetes, want agents isolated by NetworkPolicy and non-root defaults, and are willing to treat the OpenClawInstance CR as the source of truth for agent config. Do not adopt it if you want agents to edit their own config freely with no allowlist, or if you have no StatefulSet/PVC operational experience, since persistent storage and backup to S3 are part of the default path.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap between a Deployment and a working agent
An OpenClaw agent that acts across Telegram, Discord, WhatsApp and Signal needs more than a container. The README lists what the operator encodes into a single custom resource: network isolation, secret management, persistent storage, health monitoring, optional browser automation, and config rollouts. Each of those is a separate Kubernetes object that has to agree with the others. A NetworkPolicy that does not match the pod labels is silently permissive. A PVC that is not referenced by the StatefulSet template leaves the agent writing to an emptyDir that disappears on restart. The operator exists to make those objects move together.
Who is this for? Platform or infrastructure engineers who already run Kubernetes and want to self-host OpenClaw rather than use Paperclip's managed hosting, which the README explicitly names as the alternative. It is not for someone who wants an agent running in ten minutes without a cluster. The target user is comfortable with CRDs, init containers, and reading events when a reconcile fails.
One CR, nine or more reconciled objects
The unit of work is the OpenClawInstance resource in the openclaw.rocks/v1alpha1 group. The README's minimal example sets envFrom to a secret reference and enables persistence at 10Gi. From that, the operator reconciles what the README describes as 9+ Kubernetes resources: StatefulSet, Service, RBAC, NetworkPolicy, PVC, PDB, Ingress and others. The StatefulSet choice matters because agents have workspace state; a Deployment with a shared PVC would be the wrong primitive here.
Security defaults are applied without the user asking. The README states non-root UID 1000, a read-only root filesystem, all capabilities dropped, seccomp RuntimeDefault, and a default-deny NetworkPolicy. A validating webhook sits in front of the API. That combination means the first thing many teams will hit is not a crash but a blocked write: an agent that tries to install a package into the container filesystem will fail under a read-only root. The operator's answer to that is init containers, covered below.
Self-configure: agents that write to the Kubernetes API
This is the most distinctive part of the design and the part most likely to cause an incident if misconfigured. With spec.selfConfigure.enabled set to true and an allowedActions list drawn from skills, config, envVars and workspaceFiles, the agent can create OpenClawSelfConfig objects that reference its own instance and, for example, add an npm skill such as @anthropic/mcp-server-fetch. The operator validates each request against the instance's allowlist policy, refuses to let protected config keys be overwritten, and logs denied requests with a reason.
The README is direct about the consequence of leaving this off: without selfConfigure, config or skill changes the agent makes inside the container do not trigger a pod restart, and you have to delete the pod manually. That is a real operational trap. An agent that appears to have installed a skill will lose it on the next restart, and nothing in the pod status tells you why. If you want agents to adapt at runtime, selfConfigure is not optional decoration; it is the mechanism that turns an in-container change into a reconciled, durable change.
Merge, overwrite, and forcePaths
Config handling has two modes. In overwrite, the CR's config replaces what is on the PVC when the container restarts. In merge, the operator deep-merges the CR config with the PVC config, preserving runtime changes. The README notes that config is restored on every container restart via an init container, which is what makes the mode meaningful rather than a one-time copy.
forcePaths is the escape hatch for managed deployments. It lists dot-paths that the init container rebuilds from the CR on every restart even under mergeMode: merge. The README gives the intended use: keep operator-owned config such as auth, allowed providers, and the sandbox image immune to tenant edits, while user-owned config persists. This is a sensible split, but it is also a place where a mistake is quiet. If a path you consider operator-owned is not in forcePaths, a tenant can change it and the change will survive restarts. The README does not enumerate which keys are protected by default, so you have to determine that yourself from the CRD and the webhook behaviour.
Getting an instance running
Installation follows the standard operator shape, and the README's examples give the resource rather than the install command. The custom resource is applied with kubectl, as in the README's snippet:
apiVersion: openclaw.rocks/v1alpha1 kind: OpenClawInstance metadata: name: my-agent spec: envFrom: - secretRef: name: openclaw-api-keys storage: persistence: enabled: true size: 10Gi
To let the agent adapt itself, add spec.selfConfigure with enabled: true and allowedActions: [skills, config, envVars, workspaceFiles]. The agent then creates an OpenClawSelfConfig with instanceRef pointing at my-agent and, for example, addSkills listing an npm package. Suspension is a single field: spec.suspended: true scales to zero while the operator keeps managing non-runtime resources. The README also mentions spec.probes.diskReadiness, spec.skills with npm: and pack: prefixes, spec.plugins, additionalWorkspaces[].skills, and config.forcePaths as dot-paths. The repository topics include Helm, but the README excerpt supplied here does not show a chart install command, so treat the Helm path as unverified from this material and check the chart directory before assuming it.
Disk readiness and the failure it prevents
The diskReadiness option is the most interesting small design decision in the README. When enabled, the readiness probe becomes an exec check that combines the gateway's /readyz signal with a workspace writability and free-space check. A full or read-only PVC therefore removes the pod from Service endpoints instead of accepting writes it cannot persist. Liveness and startup probes stay HTTP, so a full disk does not become a CrashLoopBackOff. It is defaulted off.
That default is defensible but worth questioning. The failure it prevents, an agent that reports healthy while silently dropping writes, is exactly the kind of failure that is hard to notice until data is missing. Teams running on storage classes that can hit capacity limits should probably turn it on. The cost is that a pod with a full disk stays out of rotation rather than restarting, so you need alerting on readiness, not just on restarts, or the instance will sit unhealthy and quiet.
Backup, auto-update, and what they cost you
Backups go to S3-compatible storage on three triggers: deletion, pre-update, and a cron schedule, with restore into a new instance from any snapshot. Auto-update is opt-in and polls an OCI registry for new semver releases, backs up first, rolls out, and rolls back if the new version fails health checks. Both features imply external dependencies: an S3 endpoint and credentials for backup, and registry access for updates. Neither is free operationally. A cron backup schedule that writes to S3 accumulates objects and cost, and an auto-update path that rolls back still leaves you needing to know why the health check failed.
The README states a 5-minute drift detection loop and automatic config rollouts via content hashing. Content hashing is the standard way to trigger a restart when config changes, and it is worth knowing that it restarts pods. On a StatefulSet with a single replica, that is a brief outage per config change. There is no mention of a surge or canary mechanism for config rollouts, so plan changes accordingly.
Where a Helm chart is the better tool
The honest alternative is a Helm chart that templates the same StatefulSet, Service, NetworkPolicy and PVC, with no controller running. The difference in approach is the reconcile loop. A chart renders once at install or upgrade; the operator continuously compares desired and actual state, which is what makes drift detection, automatic rollback after a failed update, and self-healing possible. If your agents are static, if config changes ship through your normal CI pipeline, and if nobody needs to install a skill at runtime, the chart gives you the same resources with one less control plane component to upgrade and monitor.
The operator earns its place when agents change themselves. OpenClawSelfConfig has no chart equivalent: it is an API the agent calls, validated by a webhook, with an allowlist policy and audit logging of denied requests. If you do not want that, you are carrying a CRD, a webhook, and a controller for a workload a chart could describe. That is the trade, and it is a real one.
Editorial conclusion
Adopt openclaw-operator if you already run Kubernetes, want agents isolated by NetworkPolicy and non-root defaults, and are willing to treat the OpenClawInstance CR as the source of truth for agent config. Do not adopt it if you want agents to edit their own config freely with no allowlist, or if you have no StatefulSet/PVC operational experience, since persistent storage and backup to S3 are part of the default path. Before rollout, verify three things: that your cluster is 1.28 or newer, that the selfConfigure allowlist covers exactly the actions your agents need, and that config.forcePaths protects the keys you do not want tenants to overwrite.
Community notes