API Reference

Packages

• openclaw.rocks/v1alpha1

openclaw.rocks/v1alpha1

Package v1alpha1 contains API Schema definitions for the openclaw v1alpha1 API group

Resource Types

• OpenClawClusterDefaults
• OpenClawInstance
• OpenClawSelfConfig

AdditionalWorkspace

AdditionalWorkspace defines a named workspace for a secondary agent. The operator seeds files to ~/.openclaw/workspace-/.

Appears in:

• WorkspaceSpec

Field	Description	Default	Validation
name string	Name identifies this workspace. The operator seeds files to ~/.openclaw/workspace-/. Must match the workspace path configured in spec.config.raw.agents.list[].workspace.		MaxLength: 63 MinLength: 1 Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
configMapRef ConfigMapNameSelector	ConfigMapRef references an external ConfigMap whose keys become workspace files.		Optional: {}
initialFiles object (keys:string, values:string)	InitialFiles maps filenames to their content (same as spec.workspace.initialFiles).		MaxProperties: 50 Optional: {}
initialDirectories string array	InitialDirectories is a list of directories to create inside this workspace.		MaxItems: 20 Optional: {}

AutoScalingSpec

AutoScalingSpec configures horizontal pod auto-scaling via HPA

Appears in:

• AvailabilitySpec

Field	Description	Default	Validation
enabled boolean	Enabled enables HorizontalPodAutoscaler creation	false	Optional: {}
minReplicas integer	MinReplicas is the lower limit for the number of replicas	1	Minimum: 1 Optional: {}
maxReplicas integer	MaxReplicas is the upper limit for the number of replicas	5	Minimum: 1 Optional: {}
targetCPUUtilization integer	TargetCPUUtilization is the target average CPU utilization (percentage)	80	Maximum: 100 Minimum: 1 Optional: {}
targetMemoryUtilization integer	TargetMemoryUtilization is the target average memory utilization (percentage). When not set, only CPU-based scaling is used.		Maximum: 100 Minimum: 1 Optional: {}

AutoUpdateSpec

AutoUpdateSpec configures automatic version updates from the OCI registry

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables automatic version updates	false	Optional: {}
checkInterval string	CheckInterval is how often to check for new versions (Go duration, e.g. “24h”) Minimum: 1h, Maximum: 168h (7 days)	24h	Optional: {}
backupBeforeUpdate boolean	BackupBeforeUpdate creates a backup before applying updates	true	Optional: {}
rollbackOnFailure boolean	RollbackOnFailure automatically reverts to the previous version if the updated pod fails to become ready within HealthCheckTimeout	true	Optional: {}
healthCheckTimeout string	HealthCheckTimeout is how long to wait for the updated pod to become ready before triggering a rollback (Go duration, e.g. “10m”) Minimum: 2m, Maximum: 30m	10m	Optional: {}

AvailabilitySpec

AvailabilitySpec defines high availability settings

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
podDisruptionBudget PodDisruptionBudgetSpec	PodDisruptionBudget configures the PDB		Optional: {}
autoScaling AutoScalingSpec	AutoScaling configures horizontal pod auto-scaling		Optional: {}
nodeSelector object (keys:string, values:string)	NodeSelector is a selector which must match a node’s labels for the pod to be scheduled		Optional: {}
tolerations Toleration array	Tolerations are tolerations for pod scheduling		Optional: {}
affinity Affinity	Affinity specifies affinity scheduling rules		Optional: {}
topologySpreadConstraints TopologySpreadConstraint array	TopologySpreadConstraints describes how pods should spread across topology domains		Optional: {}
runtimeClassName string	RuntimeClassName refers to a RuntimeClass object in the cluster, which should be used to run this pod. If no RuntimeClass resource matches the named class, the pod will not be run. If unset or empty, the default container runtime is used. More info: https://kubernetes.io/docs/concepts/containers/runtime-class/		Optional: {}

BackupSpec

BackupSpec configures periodic scheduled backups to S3-compatible storage.

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
schedule string	Schedule is a cron expression for periodic backups (e.g., “0 2 * * *” for daily at 2 AM). When set, the operator creates a CronJob that runs rclone to sync PVC data to S3. Requires persistence to be enabled and the s3-backup-credentials Secret in the operator namespace.		Optional: {}
historyLimit integer	HistoryLimit is the number of successful CronJob runs to retain.	3	Minimum: 0 Optional: {}
failedHistoryLimit integer	FailedHistoryLimit is the number of failed CronJob runs to retain.	1	Minimum: 0 Optional: {}
timeout string	Timeout is the maximum duration to wait for a pre-delete backup to complete before giving up and proceeding with deletion (Go duration string, e.g. “30m”, “1h”). Covers all phases: StatefulSet scale-down, pod termination, Job execution, and Job failure retries. When the timeout elapses the operator logs a warning, emits a BackupTimedOut event, and removes the finalizer so deletion can proceed. Minimum: 5m, Maximum: 24h, Default: 30m.		Optional: {}
serviceAccountName string	ServiceAccountName is the name of the ServiceAccount to use for backup and restore Jobs. Use this to assign a cloud-provider workload identity ServiceAccount (e.g., AWS IRSA, GKE Workload Identity, AKS Workload Identity) so backup Jobs can authenticate to the storage backend without static credentials. When set, all backup Jobs (pre-delete, pre-update, periodic, and restore) use this SA.		Optional: {}
retentionDays integer	RetentionDays is the number of days to keep daily snapshots in S3. The periodic backup syncs incrementally to a fixed “latest” path and takes a daily snapshot. Snapshots older than RetentionDays are pruned after each successful backup.	7	Maximum: 365 Minimum: 1 Optional: {}

BootstrapSpec

BootstrapSpec controls the operator-managed BOOTSTRAP.md workspace file.

Appears in:

• WorkspaceSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether the operator injects its BOOTSTRAP.md into the default workspace. When true (the default), the init container seeds BOOTSTRAP.md on pod start if the file is not present on the PVC. Set to false if the agent has already completed bootstrap and you don’t want the operator to recreate the file on pod restart or config change. OpenClaw deletes BOOTSTRAP.md after applying it, so without this flag every restart would cause the agent to re-run bootstrap. See #463.	true	Optional: {}

CABundleSpec

CABundleSpec configures custom CA certificate injection.

Appears in:

• SecuritySpec

Field	Description	Default	Validation
configMapName string	ConfigMapName is the name of a ConfigMap containing the CA bundle. The ConfigMap should have a key matching the Key field.		Optional: {}
secretName string	SecretName is the name of a Secret containing the CA bundle. The Secret should have a key matching the Key field. Only one of ConfigMapName or SecretName should be set.		Optional: {}
key string	Key is the key in the ConfigMap or Secret containing the CA bundle.	ca-bundle.crt	Optional: {}

ChromiumImageSpec

ChromiumImageSpec defines the Chromium container image

Appears in:

• ChromiumSpec

Field	Description	Default	Validation
repository string	Repository is the container image repository	chromedp/headless-shell	Optional: {}
tag string	Tag is the container image tag	stable	Optional: {}
digest string	Digest is the container image digest for supply chain security		Optional: {}

ChromiumPersistenceSpec

ChromiumPersistenceSpec configures persistent storage for Chromium browser profiles

Appears in:

• ChromiumSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables persistent storage for the Chromium browser profile. When true, a PVC is created (or an existing one is used) and mounted at /chromium-data. The —user-data-dir flag is set automatically so that cookies, localStorage, session tokens, and cached credentials survive pod restarts.	false	Optional: {}
storageClass string	StorageClass is the name of the StorageClass to use for the PVC. If empty, the cluster default StorageClass is used.		Optional: {}
size string	Size is the requested storage size for the Chromium profile PVC.	1Gi	Optional: {}
existingClaim string	ExistingClaim is the name of a pre-existing PVC to use instead of creating a new one. When set, storageClass and size are ignored.		Optional: {}

ChromiumSpec

ChromiumSpec defines the Chromium sidecar configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables the Chromium sidecar for browser automation	false	Optional: {}
image ChromiumImageSpec	Image configures the Chromium container image		Optional: {}
resources ResourcesSpec	Resources specifies compute resources for the Chromium container		Optional: {}
persistence ChromiumPersistenceSpec	Persistence configures persistent storage for the Chromium browser profile. When enabled, browser state (cookies, localStorage, session tokens) survives pod restarts. When disabled (default), an emptyDir is used and all browser state is lost on restart.		Optional: {}
extraArgs string array	ExtraArgs specifies additional command-line arguments passed to the Chromium process. These are appended to the default arguments. Example: [“—disable-blink-features=AutomationControlled”, “—user-agent=Mozilla/5.0 …”]		Optional: {}
extraEnv EnvVar array	ExtraEnv specifies additional environment variables for the Chromium sidecar container, merged with the operator-managed variables.		Optional: {}

ConfigMapKeySelector

ConfigMapKeySelector selects a key from a ConfigMap

Appears in:

• ConfigSpec

Field	Description	Default	Validation
name string	Name of the ConfigMap
key string	Key in the ConfigMap to use	openclaw.json	Optional: {}

ConfigMapNameSelector

ConfigMapNameSelector references a ConfigMap by name. Unlike ConfigMapKeySelector, all keys in the ConfigMap are used.

Appears in:

• AdditionalWorkspace
• WorkspaceSpec

Field	Description	Default	Validation
name string	Name is the name of the ConfigMap to reference.		MinLength: 1

ConfigSpec

ConfigSpec defines the OpenClaw configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
configMapRef ConfigMapKeySelector	ConfigMapRef references a ConfigMap containing the openclaw.json configuration		Optional: {}
raw RawConfig	Raw is inline openclaw.json configuration (used if ConfigMapRef is not set)		Optional: {}
mergeMode string	MergeMode controls how operator-managed config is applied to the PVC. ”overwrite” replaces the config file on every pod restart. ”merge” deep-merges operator config with existing PVC config, preserving runtime changes.	overwrite	Enum: [overwrite merge] Optional: {}
format string	Format specifies the config file format. ”json” (default) expects standard JSON. “json5” accepts JSON5 (comments, trailing commas). JSON5 is converted to standard JSON by the init container using npx json5. JSON5 requires configMapRef (inline raw config must be valid JSON).	json	Enum: [json json5] Optional: {}

ContainerSecurityContextSpec

ContainerSecurityContextSpec defines container-level security context

Appears in:

• SecuritySpec

Field	Description	Default	Validation
allowPrivilegeEscalation boolean	AllowPrivilegeEscalation controls whether a process can gain more privileges	false	Optional: {}
readOnlyRootFilesystem boolean	ReadOnlyRootFilesystem mounts the container’s root filesystem as read-only The PVC at ~/.openclaw/ provides writable home, and a /tmp emptyDir handles temp files	true	Optional: {}
capabilities Capabilities	Capabilities to add/drop		Optional: {}
runAsNonRoot boolean	RunAsNonRoot indicates that the container must run as a non-root user. When not set, inherits from podSecurityContext.runAsNonRoot.		Optional: {}
runAsUser integer	RunAsUser is the UID to run the entrypoint of the container process. When not set, inherits from podSecurityContext.runAsUser.		Optional: {}

GatewaySpec

GatewaySpec configures the gateway reverse proxy and authentication token

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
enabled boolean	Enabled controls whether the built-in gateway reverse proxy sidecar is injected into the pod. When false, no proxy container is added and health probes target the OpenClaw gateway directly on port 18789. Defaults to true.	true	Optional: {}
existingSecret string	ExistingSecret is the name of a user-managed Secret containing the gateway token. The Secret must have a key named “token”. When set, the operator skips auto-generating a gateway token Secret and uses this Secret instead.		Optional: {}
controlUiOrigins string array	ControlUiOrigins is a list of additional allowed origins for the Control UI. The operator always auto-injects localhost origins (http://localhost:18789, http://127.0.0.1:18789) and derives origins from ingress hosts. Use this field to add extra origins (e.g., custom reverse proxy URLs).		MaxItems: 20 Optional: {}

GrafanaDashboardSpec

GrafanaDashboardSpec configures auto-provisioned Grafana dashboard ConfigMaps

Appears in:

• MetricsSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables Grafana dashboard ConfigMap creation	false	Optional: {}
labels object (keys:string, values:string)	Labels to add to the dashboard ConfigMaps (in addition to grafana_dashboard: “1”)		Optional: {}
folder string	Folder is the Grafana folder to place the dashboards in	OpenClaw	Optional: {}

ImageSpec

ImageSpec defines the container image configuration

Appears in:

• OpenClawClusterDefaultsSpec
• OpenClawInstanceSpec

Field	Description	Default	Validation
repository string	Repository is the container image repository	ghcr.io/openclaw/openclaw	Optional: {}
tag string	Tag is the container image tag	latest	Optional: {}
digest string	Digest is the container image digest (overrides tag if specified)		Optional: {}
pullPolicy PullPolicy	PullPolicy specifies when to pull the image	IfNotPresent	Enum: [Always IfNotPresent Never] Optional: {}
pullSecrets LocalObjectReference array	PullSecrets is a list of secret names for pulling from private registries		Optional: {}

IngressBasicAuthSpec

IngressBasicAuthSpec configures HTTP Basic Authentication for the Ingress.

Appears in:

• IngressSecuritySpec

Field	Description	Default	Validation
enabled boolean	Enabled enables basic authentication.	false	Optional: {}
existingSecret string	ExistingSecret is the name of an existing Secret that already contains htpasswd-formatted content in a key named “auth”. When set, the operator uses this Secret instead of generating one.		Optional: {}
username string	Username for the auto-generated htpasswd Secret. Ignored when existingSecret is set.	openclaw	MaxLength: 64 Optional: {}
realm string	Realm is the authentication realm shown in browser prompts.	OpenClaw	Optional: {}

IngressHost

IngressHost defines a host for the Ingress

Appears in:

• IngressSpec

Field	Description	Default	Validation
host string	Host is the fully qualified domain name
paths IngressPath array	Paths is a list of paths to route		Optional: {}

IngressPath

IngressPath defines a path for the Ingress

Appears in:

• IngressHost

Field	Description	Default	Validation
path string	Path is the path to route	/	Optional: {}
pathType string	PathType determines how the path should be matched	Prefix	Enum: [Prefix Exact ImplementationSpecific] Optional: {}
port integer	Port is the backend service port number to route traffic to. Defaults to the gateway port (18789) when not set.		Maximum: 65535 Minimum: 1 Optional: {}

IngressSecuritySpec

IngressSecuritySpec defines security settings for the Ingress

Appears in:

• IngressSpec

Field	Description	Default	Validation
forceHTTPS boolean	ForceHTTPS redirects all HTTP traffic to HTTPS	true	Optional: {}
enableHSTS boolean	EnableHSTS enables HTTP Strict Transport Security	true	Optional: {}
rateLimiting RateLimitingSpec	RateLimiting configures rate limiting		Optional: {}
basicAuth IngressBasicAuthSpec	BasicAuth configures HTTP Basic Authentication for the Ingress. Disabled by default. When enabled without an existingSecret, the operator auto-generates a random password and stores it in a managed Secret.		Optional: {}

IngressSpec

IngressSpec defines the Ingress configuration

Appears in:

• NetworkingSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables Ingress creation	false	Optional: {}
className string	ClassName is the name of the IngressClass to use		Optional: {}
annotations object (keys:string, values:string)	Annotations to add to the Ingress		Optional: {}
hosts IngressHost array	Hosts is a list of hosts to route traffic for		Optional: {}
tls IngressTLS array	TLS configuration		Optional: {}
security IngressSecuritySpec	Security configures ingress security settings		Optional: {}

IngressTLS

IngressTLS defines TLS configuration for the Ingress

Appears in:

• IngressSpec

Field	Description	Default	Validation
hosts string array	Hosts are a list of hosts included in the TLS certificate
secretName string	SecretName is the name of the secret containing the TLS certificate

LoggingSpec

LoggingSpec defines logging configuration

Appears in:

• ObservabilitySpec

Field	Description	Default	Validation
level string	Level is the log level	info	Enum: [debug info warn error] Optional: {}
format string	Format is the log format	json	Enum: [json text] Optional: {}

MetricsSpec

MetricsSpec defines metrics configuration

Appears in:

• ObservabilitySpec

Field	Description	Default	Validation
enabled boolean	Enabled enables metrics endpoint	true	Optional: {}
port integer	Port is the port to expose metrics on	9090	Optional: {}
serviceMonitor ServiceMonitorSpec	ServiceMonitor configures the Prometheus ServiceMonitor		Optional: {}
prometheusRule PrometheusRuleSpec	PrometheusRule configures auto-provisioned PrometheusRule alerts		Optional: {}
grafanaDashboard GrafanaDashboardSpec	GrafanaDashboard configures auto-provisioned Grafana dashboard ConfigMaps		Optional: {}

NetworkPolicySpec

NetworkPolicySpec configures network isolation for the OpenClaw instance

Appears in:

• SecuritySpec

Field	Description	Default	Validation
enabled boolean	Enabled enables network policy creation	true	Optional: {}
allowedIngressCIDRs string array	AllowedIngressCIDRs is a list of CIDRs allowed to access this instance		Optional: {}
allowedIngressNamespaces string array	AllowedIngressNamespaces is a list of namespace names allowed to access this instance		Optional: {}
allowedEgressCIDRs string array	AllowedEgressCIDRs is a list of CIDRs this instance can reach Default allows all egress on port 443 for AI APIs		Optional: {}
allowDNS boolean	AllowDNS allows DNS resolution (port 53)	true	Optional: {}
additionalEgress NetworkPolicyEgressRule array	AdditionalEgress appends custom egress rules to the default DNS + HTTPS rules. Use this to allow traffic to cluster-internal services on non-standard ports.		Optional: {}

NetworkingSpec

NetworkingSpec defines network-related configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
service ServiceSpec	Service configures the Kubernetes Service		Optional: {}
ingress IngressSpec	Ingress configures the Kubernetes Ingress		Optional: {}

ObservabilitySpec

ObservabilitySpec defines observability configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
metrics MetricsSpec	Metrics configures Prometheus metrics		Optional: {}
logging LoggingSpec	Logging configures logging		Optional: {}

OllamaImageSpec

OllamaImageSpec defines the Ollama container image

Appears in:

• OllamaSpec

Field	Description	Default	Validation
repository string	Repository is the container image repository	ollama/ollama	Optional: {}
tag string	Tag is the container image tag	latest	Optional: {}
digest string	Digest is the container image digest for supply chain security		Optional: {}

OllamaSpec

OllamaSpec defines the Ollama sidecar configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables the Ollama sidecar	false	Optional: {}
image OllamaImageSpec	Image configures the Ollama container image		Optional: {}
models string array	Models is a list of models to pre-pull during pod init (e.g. [“llama3.2”, “nomic-embed-text”])		MaxItems: 10 Optional: {}
resources ResourcesSpec	Resources specifies compute resources for the Ollama container		Optional: {}
storage OllamaStorageSpec	Storage configures the model cache volume		Optional: {}
gpu integer	GPU is the number of NVIDIA GPUs to allocate (sets nvidia.com/gpu resource limit)		Minimum: 0 Optional: {}

OllamaStorageSpec

OllamaStorageSpec configures the Ollama model cache volume

Appears in:

• OllamaSpec

Field	Description	Default	Validation
sizeLimit string	SizeLimit is the size limit for the emptyDir model cache (default “20Gi”)	20Gi	Optional: {}
existingClaim string	ExistingClaim is the name of an existing PVC for persistent model storage		Optional: {}

OpenClawClusterDefaults

OpenClawClusterDefaults is a cluster-scoped singleton (name must be “cluster”) that provides default values merged into every OpenClawInstance at reconcile time. It exists so platform operators managing air-gapped or restricted-network environments can set a single source of truth for image registry mirrors, shared environment variables (e.g. NPM_CONFIG_REGISTRY, PIP_INDEX_URL), and runtime-dep init containers without duplicating the same boilerplate in every OpenClawInstance manifest.

Precedence: per-instance fields always win over cluster defaults. A default is only applied when the corresponding instance field is unset.

Field	Description	Default	Validation
apiVersion string	openclaw.rocks/v1alpha1
kind string	OpenClawClusterDefaults
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec OpenClawClusterDefaultsSpec

OpenClawClusterDefaultsSpec

OpenClawClusterDefaultsSpec defines cluster-wide defaults that the operator applies to every OpenClawInstance at reconcile time. Per-instance fields always win: a default is only applied when the instance field is unset.

Appears in:

• OpenClawClusterDefaults

Field	Description	Default	Validation
registry string	Registry is the default container image registry override applied to instances where spec.registry is unset. Replaces the registry prefix of all container images (main, sidecars, init containers). Example: “my-registry.example.com”.		Optional: {}
image ImageSpec	Image is the default container image configuration applied to instances where the corresponding instance fields are unset. Each sub-field is merged independently (e.g. a cluster-default tag still applies even when the instance sets its own repository).		Optional: {}
env EnvVar array	Env is a list of default environment variables merged into every instance’s container env. Instance-level env entries with the same Name override the cluster default for that name. Defaults appear first in the resulting env list, followed by instance-only names.		Optional: {}
runtimeDeps RuntimeDepsSpec	RuntimeDeps configures the default set of built-in init containers (pnpm, Python) applied to instances where the corresponding fields are unset. A cluster default of true for a runtime dep is always applied unless the instance explicitly opts out (sets the field to false). NOTE: because RuntimeDepsSpec fields are plain booleans, “unset” and ”false” are indistinguishable; cluster defaults are OR-merged here.		Optional: {}

OpenClawInstance

OpenClawInstance is the Schema for the openclawinstances API

Field	Description	Default	Validation
apiVersion string	openclaw.rocks/v1alpha1
kind string	OpenClawInstance
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec OpenClawInstanceSpec

OpenClawInstanceSpec

OpenClawInstanceSpec defines the desired state of OpenClawInstance

Appears in:

• OpenClawInstance

Field	Description	Default	Validation
registry string	Registry is the global container image registry override. When set, this registry replaces the registry part of all container images used by the instance (main container, sidecars, init containers). Example: “my-registry.example.com” will change “ghcr.io/openclaw/openclaw:latest” to “my-registry.example.com/openclaw/openclaw:latest”.		Optional: {}
image ImageSpec	Image configuration for the OpenClaw container		Optional: {}
config ConfigSpec	Config specifies the OpenClaw configuration		Optional: {}
workspace WorkspaceSpec	Workspace configures initial workspace files seeded into the instance. Files are copied once on first boot and never overwritten, so agent modifications survive pod restarts.		Optional: {}
skills string array	Skills is a list of skills to install via init container. Each entry is either a ClawHub skill identifier (e.g., “@anthropic/mcp-server-fetch”) or an npm package prefixed with “npm:” (e.g., “npm:@openclaw/matrix”). npm lifecycle scripts are disabled for security (see #91).		MaxItems: 20 Optional: {}
plugins string array	Plugins is a list of plugins to install via init container. Each entry is an npm package name (e.g., “@openclaw/matrix” or ”@martian-engineering/lossless-claw”). An optional “npm:” prefix is accepted and stripped before installation. Installation goes through the OpenClaw CLI’s ClawHub installer (“openclaw plugins install clawhub:”) rather than raw npm install so packages published with workspace:* dependency markers resolve correctly. npm lifecycle scripts are disabled for security.		MaxItems: 20 Optional: {}
envFrom EnvFromSource array	EnvFrom is a list of sources to populate environment variables from Use this for API keys and other secrets (e.g., ANTHROPIC_API_KEY, OPENAI_API_KEY)		Optional: {}
env EnvVar array	Env is a list of environment variables to set in the container		Optional: {}
resources ResourcesSpec	Resources specifies the compute resources for the OpenClaw container		Optional: {}
security SecuritySpec	Security specifies security-related configuration		Optional: {}
shareProcessNamespace boolean	ShareProcessNamespace enables PID namespace sharing between all containers in the pod. When true, the infrastructure (pause) container becomes PID 1 and reaps zombie processes, which prevents accumulation of defunct helper processes (git, plugins, QMD memory, shells) under a Node.js gateway that does not call waitpid(). Defaults to true. Security note: enabling this lets every container in the pod see and signal every other container’s processes. A compromised sidecar (Tailscale, Ollama, browser, custom) could send signals to the gateway and vice versa. Set to false to keep per-container PID isolation; you are then responsible for reaping zombies (e.g. by baking tini or dumb-init into the image).	true	Optional: {}
storage StorageSpec	Storage specifies persistent storage configuration		Optional: {}
chromium ChromiumSpec	Chromium enables the Chromium sidecar for browser automation		Optional: {}
tailscale TailscaleSpec	Tailscale configures Tailscale integration for tailnet access and HTTPS		Optional: {}
ollama OllamaSpec	Ollama enables the Ollama sidecar for local LLM inference		Optional: {}
webTerminal WebTerminalSpec	WebTerminal enables a browser-based terminal (ttyd) sidecar for debugging		Optional: {}
initContainers Container array	InitContainers is a list of additional init containers to run before the main container. They run after the operator-managed init-config and init-skills containers.		MaxItems: 10 Optional: {}
sidecars Container array	Sidecars is a list of additional sidecar containers to inject into the pod. Use this for custom sidecars like database proxies, log forwarders, or service meshes.		Optional: {}
sidecarVolumes Volume array	SidecarVolumes is a list of additional volumes to make available to sidecar containers.		Optional: {}
extraVolumes Volume array	ExtraVolumes adds additional volumes to the pod. These volumes are available to the main container via ExtraVolumeMounts.		MaxItems: 10 Optional: {}
extraVolumeMounts VolumeMount array	ExtraVolumeMounts adds additional volume mounts to the main container. Use with ExtraVolumes to mount ConfigMaps, Secrets, NFS shares, or CSI volumes.		MaxItems: 10 Optional: {}
networking NetworkingSpec	Networking specifies network-related configuration		Optional: {}
probes ProbesSpec	Probes configures health probes for the OpenClaw container		Optional: {}
observability ObservabilitySpec	Observability configures metrics and logging		Optional: {}
availability AvailabilitySpec	Availability configures high availability settings		Optional: {}
suspended boolean	Suspended scales the workload to zero replicas when true. Non-runtime resources (Service, ConfigMap, RBAC, NetworkPolicy, PVC) remain fully managed. Set to false to resume normal operation.	false	Optional: {}
backup BackupSpec	Backup configures periodic scheduled backups to S3-compatible storage. Requires the s3-backup-credentials Secret in the operator namespace and persistence enabled.		Optional: {}
restoreFrom string	RestoreFrom is the remote backup path to restore data from (e.g. “backups/{tenantId}/{instanceId}/{timestamp}”). When set, the operator restores PVC data from this path before creating the StatefulSet. Cleared automatically after successful restore.		Optional: {}
runtimeDeps RuntimeDepsSpec	RuntimeDeps configures built-in init containers that install runtime dependencies (pnpm, Python) for MCP servers and skills.		Optional: {}
gateway GatewaySpec	Gateway configures the gateway reverse proxy and authentication token		Optional: {}
autoUpdate AutoUpdateSpec	AutoUpdate configures automatic version updates from the OCI registry		Optional: {}
selfConfigure SelfConfigureSpec	SelfConfigure enables agents to modify their own instance via OpenClawSelfConfig resources. When enabled, the operator injects RBAC, env vars, and a helper skill into the workspace.		Optional: {}
podAnnotations object (keys:string, values:string)	PodAnnotations are extra annotations merged into the pod template metadata. Operator-managed annotations (e.g. config-hash) take precedence on conflict.		Optional: {}

OpenClawSelfConfig

OpenClawSelfConfig is the Schema for the openclawselfconfigs API. It represents a request from an agent to modify its own OpenClawInstance spec.

Field	Description	Default	Validation
apiVersion string	openclaw.rocks/v1alpha1
kind string	OpenClawSelfConfig
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec OpenClawSelfConfigSpec

OpenClawSelfConfigSpec

OpenClawSelfConfigSpec defines the desired changes to an OpenClawInstance.

Appears in:

• OpenClawSelfConfig

Field	Description	Default	Validation
instanceRef string	InstanceRef is the name of the parent OpenClawInstance in the same namespace.		MinLength: 1
addSkills string array	AddSkills is a list of skills to add to the instance.		MaxItems: 10 Optional: {}
removeSkills string array	RemoveSkills is a list of skills to remove from the instance.		MaxItems: 10 Optional: {}
configPatch RawConfig	ConfigPatch is a partial JSON configuration to deep-merge into the instance config.		Optional: {}
addWorkspaceFiles object (keys:string, values:string)	AddWorkspaceFiles maps filenames to content to add to the workspace.		MaxProperties: 10 Optional: {}
removeWorkspaceFiles string array	RemoveWorkspaceFiles is a list of workspace filenames to remove.		MaxItems: 10 Optional: {}
addEnvVars SelfConfigEnvVar array	AddEnvVars is a list of environment variables to add (plain values only).		MaxItems: 10 Optional: {}
removeEnvVars string array	RemoveEnvVars is a list of environment variable names to remove.		MaxItems: 10 Optional: {}

PersistenceSpec

PersistenceSpec defines PVC configuration

Appears in:

• StorageSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables persistent storage	true	Optional: {}
storageClass string	StorageClass is the name of the StorageClass to use		Optional: {}
size string	Size is the size of the PVC (e.g., “10Gi”)	10Gi	Optional: {}
accessModes PersistentVolumeAccessMode array	AccessModes contains the desired access modes for the PVC	[ReadWriteOnce]	Optional: {}
existingClaim string	ExistingClaim is the name of an existing PVC to use		Optional: {}
orphan boolean	Orphan controls whether the PVC is retained when the OpenClawInstance is deleted. When true (the default), the operator removes the owner reference from the PVC before deleting the CR so Kubernetes does not garbage-collect it. Set to false if you want the PVC deleted together with the CR.	true	Optional: {}

PodDisruptionBudgetSpec

PodDisruptionBudgetSpec defines PDB configuration

Appears in:

• AvailabilitySpec

Field	Description	Default	Validation
enabled boolean	Enabled enables PDB creation	true	Optional: {}
maxUnavailable integer	MaxUnavailable is the maximum number of pods that can be unavailable during disruption	1	Optional: {}

PodSecurityContextSpec

PodSecurityContextSpec defines pod-level security context

Appears in:

• SecuritySpec

Field	Description	Default	Validation
runAsUser integer	RunAsUser is the UID to run the entrypoint of the container process	1000	Optional: {}
runAsGroup integer	RunAsGroup is the GID to run the entrypoint of the container process	1000	Optional: {}
fsGroup integer	FSGroup is a special supplemental group that applies to all containers	1000	Optional: {}
fsGroupChangePolicy PodFSGroupChangePolicy	FSGroupChangePolicy defines the behavior of changing ownership and permission of the volume. ”OnRootMismatch” skips recursive chown when ownership already matches, improving startup time for large PVCs. “Always” recursively chowns on every mount (Kubernetes default).		Enum: [OnRootMismatch Always] Optional: {}
runAsNonRoot boolean	RunAsNonRoot indicates that the container must run as a non-root user	true	Optional: {}

ProbeSpec

ProbeSpec defines a health probe

Appears in:

• ProbesSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables the probe	true	Optional: {}
initialDelaySeconds integer	InitialDelaySeconds is the number of seconds after the container starts before the probe is initiated		Optional: {}
periodSeconds integer	PeriodSeconds is how often (in seconds) to perform the probe		Optional: {}
timeoutSeconds integer	TimeoutSeconds is the number of seconds after which the probe times out		Optional: {}
failureThreshold integer	FailureThreshold is the number of times to retry before giving up		Optional: {}

ProbesSpec

ProbesSpec defines health probe configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
liveness ProbeSpec	Liveness probe configuration		Optional: {}
readiness ProbeSpec	Readiness probe configuration		Optional: {}
startup ProbeSpec	Startup probe configuration		Optional: {}

PrometheusRuleSpec

PrometheusRuleSpec configures auto-provisioned PrometheusRule alerts

Appears in:

• MetricsSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables PrometheusRule creation with operator alerts	false	Optional: {}
labels object (keys:string, values:string)	Labels to add to the PrometheusRule (e.g., for Prometheus rule selector matching)		Optional: {}
runbookBaseURL string	RunbookBaseURL is the base URL for alert runbook links	https://openclaw.rocks/docs/runbooks	Optional: {}

RBACRule

RBACRule represents a RBAC rule

Appears in:

• RBACSpec

Field	Description	Default	Validation
apiGroups string array	APIGroups is the name of the APIGroup that contains the resources
resources string array	Resources is a list of resources this rule applies to
verbs string array	Verbs is a list of verbs that apply to the resources

RBACSpec

RBACSpec configures RBAC for the OpenClaw instance

Appears in:

• SecuritySpec

Field	Description	Default	Validation
createServiceAccount boolean	CreateServiceAccount creates a dedicated ServiceAccount for the instance	true	Optional: {}
serviceAccountName string	ServiceAccountName is the name of an existing ServiceAccount to use Only used if CreateServiceAccount is false		Optional: {}
serviceAccountAnnotations object (keys:string, values:string)	ServiceAccountAnnotations are annotations to add to the managed ServiceAccount. Use this for cloud provider integrations like AWS IRSA or GCP Workload Identity.		Optional: {}
additionalRules RBACRule array	AdditionalRules adds custom RBAC rules to the generated Role		Optional: {}

RateLimitingSpec

RateLimitingSpec defines rate limiting configuration

Appears in:

• IngressSecuritySpec

Field	Description	Default	Validation
enabled boolean	Enabled enables rate limiting	true	Optional: {}
requestsPerSecond integer	RequestsPerSecond is the maximum requests per second	10	Optional: {}

RawConfig

RawConfig holds arbitrary JSON configuration for openclaw.json

Appears in:

• ConfigSpec
• OpenClawSelfConfigSpec

ResourcesSpec

ResourcesSpec defines compute resource requirements

Appears in:

• ChromiumSpec
• OllamaSpec
• OpenClawInstanceSpec
• TailscaleSpec
• WebTerminalSpec

RuntimeDepsSpec

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

Appears in:

• OpenClawClusterDefaultsSpec
• OpenClawInstanceSpec

Field	Description	Default	Validation
pnpm boolean	Pnpm installs pnpm via corepack for npm-based MCP servers and skills.		Optional: {}
python boolean	Python installs Python 3.12 and uv for Python-based MCP servers and skills.		Optional: {}

SecuritySpec

SecuritySpec defines security-related configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
podSecurityContext PodSecurityContextSpec	PodSecurityContext holds pod-level security attributes		Optional: {}
containerSecurityContext ContainerSecurityContextSpec	ContainerSecurityContext holds container-level security attributes		Optional: {}
networkPolicy NetworkPolicySpec	NetworkPolicy configures network isolation		Optional: {}
rbac RBACSpec	RBAC configures role-based access control		Optional: {}
caBundle CABundleSpec	CABundle injects a custom CA certificate bundle into all containers. Use this in environments with TLS-intercepting proxies or private CAs.		Optional: {}

SelfConfigAction

Underlying type: string

SelfConfigAction represents an action category that can be allowed for self-configuration.

Validation:

• Enum: [skills config workspaceFiles envVars]

Appears in:

• SelfConfigureSpec

Field	Description
skills
config
workspaceFiles
envVars

SelfConfigEnvVar

SelfConfigEnvVar defines a plain-value environment variable (no secret refs).

Appears in:

• OpenClawSelfConfigSpec

Field	Description	Default	Validation
name string	Name of the environment variable.		MinLength: 1
value string	Value of the environment variable.

SelfConfigureSpec

SelfConfigureSpec configures whether an agent can modify its own instance.

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables self-configuration for this instance. When true, the agent can create OpenClawSelfConfig resources to modify its own spec.	false	Optional: {}
allowedActions SelfConfigAction array	AllowedActions restricts which action categories the agent can perform. If empty and enabled is true, no actions are allowed (fail-safe).		Enum: [skills config workspaceFiles envVars] MaxItems: 4 Optional: {}

ServiceMonitorSpec

ServiceMonitorSpec defines the ServiceMonitor configuration

Appears in:

• MetricsSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables ServiceMonitor creation	false	Optional: {}
interval string	Interval is the scrape interval	30s	Optional: {}
labels object (keys:string, values:string)	Labels to add to the ServiceMonitor		Optional: {}

ServicePortSpec

ServicePortSpec defines a port exposed by the Service

Appears in:

• ServiceSpec

Field	Description	Default	Validation
name string	Name is the name of the port		MinLength: 1
port integer	Port is the port number exposed on the Service		Maximum: 65535 Minimum: 1
targetPort integer	TargetPort is the port on the container to route to (defaults to Port)		Maximum: 65535 Minimum: 1 Optional: {}
protocol Protocol	Protocol is the protocol for the port	TCP	Enum: [TCP UDP SCTP] Optional: {}

ServiceSpec

ServiceSpec defines the Service configuration

Appears in:

• NetworkingSpec

Field	Description	Default	Validation
type ServiceType	Type is the Kubernetes Service type	ClusterIP	Enum: [ClusterIP LoadBalancer NodePort] Optional: {}
annotations object (keys:string, values:string)	Annotations to add to the Service		Optional: {}
ports ServicePortSpec array	Ports defines custom ports exposed on the Service. When set, these replace the default gateway and canvas ports. When empty, the operator creates default gateway (18789) and canvas (18793) ports.		MaxItems: 20 Optional: {}

StorageSpec

StorageSpec defines persistent storage configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
persistence PersistenceSpec	Persistence configures the PersistentVolumeClaim		Optional: {}

TailscaleImageSpec

TailscaleImageSpec defines the Tailscale sidecar container image

Appears in:

• TailscaleSpec

Field	Description	Default	Validation
repository string	Repository is the container image repository	ghcr.io/tailscale/tailscale	Optional: {}
tag string	Tag is the container image tag	latest	Optional: {}
digest string	Digest is the container image digest for supply chain security		Optional: {}

TailscaleSpec

TailscaleSpec configures Tailscale integration for secure tailnet access. When enabled, a Tailscale sidecar container runs tailscaled and handles serve/funnel via TS_SERVE_CONFIG. An init container copies the tailscale CLI binary to a shared volume so the main container can call “tailscale whois” for SSO authentication.

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables Tailscale integration	false	Optional: {}
mode string	Mode selects the Tailscale mode. ”serve” exposes the instance to tailnet members only (default). “funnel” exposes the instance to the public internet via Tailscale Funnel.	serve	Enum: [serve funnel] Optional: {}
image TailscaleImageSpec	Image configures the Tailscale sidecar container image. The same image is used for the sidecar and the init container that copies the tailscale CLI binary.		Optional: {}
authKeySecretRef LocalObjectReference	AuthKeySecretRef references a Secret containing the Tailscale auth key. The Secret must have a key matching AuthKeySecretKey (default: “authkey”). Use ephemeral+reusable keys from the Tailscale admin console.		Optional: {}
authKeySecretKey string	AuthKeySecretKey is the key in the referenced Secret.	authkey	Optional: {}
hostname string	Hostname sets the Tailscale device name (defaults to instance name).		Optional: {}
authSSO boolean	AuthSSO enables passwordless login for tailnet members. Sets gateway.auth.allowTailscale=true in the OpenClaw config.	false	Optional: {}
resources ResourcesSpec	Resources specifies compute resources for the Tailscale sidecar container.		Optional: {}

WebTerminalCredentialSpec

WebTerminalCredentialSpec configures basic auth for the web terminal

Appears in:

• WebTerminalSpec

Field	Description	Default	Validation
secretRef LocalObjectReference	SecretRef references a Secret containing “username” and “password” keys

WebTerminalImageSpec

WebTerminalImageSpec defines the ttyd container image

Appears in:

• WebTerminalSpec

Field	Description	Default	Validation
repository string	Repository is the container image repository	tsl0922/ttyd	Optional: {}
tag string	Tag is the container image tag	latest	Optional: {}
digest string	Digest is the container image digest for supply chain security		Optional: {}

WebTerminalSpec

WebTerminalSpec defines the ttyd web terminal sidecar configuration

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
enabled boolean	Enabled enables the ttyd web terminal sidecar for browser-based shell access	false	Optional: {}
image WebTerminalImageSpec	Image configures the ttyd container image		Optional: {}
resources ResourcesSpec	Resources specifies compute resources for the ttyd container		Optional: {}
readOnly boolean	ReadOnly starts ttyd in read-only mode (view-only, no input)	false	Optional: {}
credential WebTerminalCredentialSpec	Credential configures basic auth for the web terminal via a Secret. The Secret must have “username” and “password” keys.		Optional: {}

WorkspaceSpec

WorkspaceSpec configures initial workspace files for the instance. Files listed in InitialFiles are seeded once (only if they don’t already exist on the PVC), so agent modifications survive pod restarts.

Appears in:

• OpenClawInstanceSpec

Field	Description	Default	Validation
configMapRef ConfigMapNameSelector	ConfigMapRef references an external ConfigMap whose keys become workspace files. All keys in the referenced ConfigMap are included as workspace files. This is useful for GitOps workflows where workspace files (AGENT.md, SOUL.md, etc.) are managed as standalone files and bundled via Kustomize configMapGenerator or similar. Merge priority (highest wins): 1. Operator-injected files (ENVIRONMENT.md, BOOTSTRAP.md, SELFCONFIG.md, selfconfig.sh) 2. Inline initialFiles 3. External configMapRef entries 4. Skill pack files		Optional: {}
initialFiles object (keys:string, values:string)	InitialFiles maps filenames to their content. Each file is written to the workspace directory only if it does not already exist.		MaxProperties: 50 Optional: {}
initialDirectories string array	InitialDirectories is a list of directories to create (mkdir -p) inside the workspace directory. Nested paths like “tools/scripts” are allowed.		MaxItems: 20 Optional: {}
additionalWorkspaces AdditionalWorkspace array	AdditionalWorkspaces configures workspace files for secondary agents. Each entry seeds files to ~/.openclaw/workspace-/, matching the workspace path configured in spec.config.raw.agents.list[].workspace.		MaxItems: 10 Optional: {}
bootstrap BootstrapSpec	Bootstrap controls the operator-managed BOOTSTRAP.md file injected into the default workspace to guide first-run agent onboarding.		Optional: {}