Skip to content

api-reference.md

Latest commit

 

History

History
1244 lines (665 loc) · 59.8 KB

api-reference.md

File metadata and controls

1244 lines (665 loc) · 59.8 KB

API Reference

Packages

openclaw.rocks/v1alpha1

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

Resource Types

AdditionalWorkspace

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

Appears in:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

ResourcesSpec

ResourcesSpec defines compute resource requirements

Appears in:

RuntimeDepsSpec

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

Appears in:

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:

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:

Field Description
skills
config
workspaceFiles
envVars

SelfConfigEnvVar

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

Appears in:

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:

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:

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:

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:

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:

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

TailscaleImageSpec

TailscaleImageSpec defines the Tailscale sidecar container image

Appears in:

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:

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:

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

WebTerminalImageSpec

WebTerminalImageSpec defines the ttyd container image

Appears in:

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:

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:

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: {}