Skip to content

api-reference.md

Latest commit

 

History

History
1438 lines (779 loc) · 74.6 KB

api-reference.md

File metadata and controls

1438 lines (779 loc) · 74.6 KB
Raw

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: {}
skills string array Skills is a list of skills to install scoped to this workspace, using the
same reference formats as the top-level spec.skills: a ClawHub skill
identifier (installed into workspace-/skills/ via clawhub's
--workdir), an npm package prefixed with "npm:" (npm binaries are
installed globally and shared across workspaces), or a GitHub-hosted
skill pack prefixed with "pack:" (resolved files are seeded into
workspace-/ and reconciled per spec.skillPackUpdatePolicy).		 MaxItems: 20
Optional: {}
fileUpdatePolicy WorkspaceFileUpdatePolicy FileUpdatePolicy is the default update policy for files seeded into this
workspace. When unset it inherits spec.workspace.fileUpdatePolicy, so the
default workspace and its secondaries cannot silently drift apart.		 Enum: [CreateOnly Replace]
Optional: {}
managedFiles ManagedWorkspaceFile array ManagedFiles declares per-path update policies for this workspace,
overriding its effective FileUpdatePolicy for the listed paths.		 MaxItems: 50
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 docker.io/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: {}
forcePaths string array ForcePaths is a list of dot-separated config paths (e.g. "gateway",
"models.providers", "agents.defaults.sandbox") that the init container
force-overwrites from the operator-managed config on every pod restart,
even under mergeMode=merge. For each listed path, the subtree is first
deleted from the existing PVC config and then re-applied via deep merge
from spec.config.raw, so the final value matches the CR exactly.
Use case: a managed deployer (operator of a multi-tenant openclaw
service) wants tenants to persist user-owned config across restarts
(channels.telegram.botToken, settings, etc -- requires mergeMode=merge)
but must guarantee that operator-owned paths (gateway auth tokens,
allowed model providers, sandbox image) are always rebuilt from the CR.
Without forcePaths, a tenant could persist e.g.
models.providers..apiKey via the Control UI and route inference
through their own third-party key while consuming the deployer's
compute -- a verified attack path.
Only applies when mergeMode=merge. Ignored (and rejected by the
validating webhook) under mergeMode=overwrite, which already overwrites
the entire config file on every restart.		 MaxItems: 20
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: {}

DiskReadinessSpec

DiskReadinessSpec configures the optional disk-aware readiness guard for PVC-backed OpenClaw workspaces.

Appears in:

Field Description Default Validation
enabled boolean Enabled turns on the disk-aware readiness guard. Defaults to false, so
existing deployments are unaffected unless they explicitly opt in.		 false Optional: {}
path string Path is the workspace mount path checked for writability and free space.
Defaults to the OpenClaw workspace data mount (/home/openclaw/.openclaw).		 Optional: {}
minFree string MinFree is the minimum free space the workspace volume must have for the
pod to be considered Ready, expressed as a Kubernetes quantity
(e.g. "100Mi", "1Gi"). Defaults to "64Mi".		 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: {}

HTTPRouteParentRef

HTTPRouteParentRef identifies a Gateway that the HTTPRoute attaches to

Appears in:

Field Description Default Validation
name string Name is the name of the Gateway MinLength: 1
namespace string Namespace is the namespace of the Gateway.
Defaults to the same namespace as the HTTPRoute.		 Optional: {}
sectionName string SectionName is the name of a specific listener on the Gateway to attach to. Optional: {}

HTTPRouteSpec

HTTPRouteSpec defines a Gateway API HTTPRoute configuration

Appears in:

Field Description Default Validation
enabled boolean Enabled enables HTTPRoute creation false Optional: {}
parentRefs HTTPRouteParentRef array ParentRefs specifies the Gateways this HTTPRoute attaches to.
Each ref identifies a Gateway by name (and optionally namespace and sectionName).		 Optional: {}
hostnames string array Hostnames specifies the hostnames matched by this HTTPRoute. 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: {}
annotations object (keys:string, values:string) Annotations to add to the HTTPRoute 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: {}

ManagedWorkspaceFile

ManagedWorkspaceFile declares the update policy for a single workspace file.

Appears in:

Field Description Default Validation
path string Path is the workspace-relative destination path, e.g. "AGENTS.md" or
"docs/BOUNDARIES.md". Absolute paths and ".." traversal are rejected.		 MaxLength: 253
MinLength: 1
Pattern: ^[^/].*$
updatePolicy WorkspaceFileUpdatePolicy UpdatePolicy overrides the workspace-level FileUpdatePolicy for this path.
Defaults to Replace, since listing a path here is an explicit statement
that the operator owns it.		 Replace Enum: [CreateOnly Replace]
Optional: {}

MetricsIngressFrom

Underlying type: string

MetricsIngressFrom selects which peers may reach the metrics port

Appears in:

Field Description
SameNamespace MetricsIngressFromSameNamespace allows the instance's own namespace (default)
AllowedPeers MetricsIngressFromAllowedPeers allows only the explicitly named namespaces and CIDRs
None MetricsIngressFromNone emits no metrics ingress rule

MetricsIngressSpec

MetricsIngressSpec configures NetworkPolicy ingress for the metrics port.

The /metrics endpoint is unauthenticated, so in a shared namespace every other workload could scrape it. Application allowlists (security.networkPolicy.allowedIngressNamespaces / allowedIngressCIDRs) no longer imply metrics access -- metrics peers are configured here instead.

Appears in:

Field Description Default Validation
from MetricsIngressFrom From selects which peers may reach the metrics port.
SameNamespace (the default) allows the instance's own namespace, matching
the behavior from before this field existed. AllowedPeers restricts access
to the namespaces and CIDRs named below, which is the setting to use when
only a Prometheus workload should scrape. None emits no metrics ingress
rule at all, for setups where a sidecar or node agent collects locally.
None is not an absolute deny: Kubernetes NetworkPolicies are additive, so
another policy in the namespace can still grant access.		 SameNamespace Enum: [SameNamespace AllowedPeers None]
Optional: {}
allowedNamespaces string array AllowedNamespaces lists namespaces allowed to reach the metrics port when
From is AllowedPeers.		 Optional: {}
allowedCIDRs string array AllowedCIDRs lists IP ranges allowed to reach the metrics port when From
is AllowedPeers, for collectors that live outside the cluster.		 Optional: {}
podSelector LabelSelector PodSelector further narrows the namespace peers to specific pods, e.g. the
Prometheus workload itself. It applies only to namespace peers, never to
CIDR peers, and is ignored unless From is AllowedPeers.		 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: {}

NetBirdImageSpec

NetBirdImageSpec defines the NetBird sidecar container image

Appears in:

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

NetBirdSpec

NetBirdSpec defines the NetBird overlay network configuration.

NetBird is a self-hostable alternative to Tailscale: a WireGuard data plane with a control plane you can run yourself. Only one mesh provider may be enabled per instance.

Appears in:

Field Description Default Validation
enabled boolean Enabled enables the NetBird sidecar. false Optional: {}
image NetBirdImageSpec Image configures the NetBird sidecar container image. Optional: {}
setupKeySecretRef LocalObjectReference SetupKeySecretRef references a Secret containing the NetBird setup key
used to enroll this peer. The Secret must have a key matching
SetupKeySecretKey (default: "setupkey"). Use a reusable, ephemeral setup
key from the NetBird dashboard.		 Optional: {}
setupKeySecretKey string SetupKeySecretKey is the key in the referenced Secret. setupkey Optional: {}
managementURL string ManagementURL points at a self-hosted NetBird management server, e.g.
"https://netbird.example.com:33073". Defaults to NetBird's hosted
control plane when unset.		 Optional: {}
hostname string Hostname sets the NetBird peer name (defaults to the instance name). Optional: {}
resources ResourcesSpec Resources specifies compute resources for the NetBird sidecar container. 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: {}
httpRoute HTTPRouteSpec HTTPRoute configures a Gateway API HTTPRoute.
This is an alternative to Ingress for clusters using the Gateway API
(gateway.networking.k8s.io). The Gateway API CRDs must be installed.		 Optional: {}
metricsIngress MetricsIngressSpec MetricsIngress controls who may reach the metrics port in the generated
NetworkPolicy, independently of application traffic. When unset, the
metrics port stays reachable from the instance's own namespace, which is
the pre-existing behavior.		 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 docker.io/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: {}
skillPackUpdatePolicy string SkillPackUpdatePolicy controls how workspace files seeded from "pack:"
skill entries are reconciled on pod start.
"Replace" (default) converges seeded pack files to the declared pack
revision on every pod start: changed files are overwritten and files that
were seeded by a previous revision but are no longer part of any declared
pack are removed. The operator tracks the seeded file set in a manifest
at /data/.skillpack-manifest on the data volume.
"CreateOnly" preserves the legacy behavior: pack files are only copied
when absent and never overwritten or removed, so updating a pinned pack
revision does not refresh already-seeded contents (see #564).
Only files at paths declared by pack: entries are affected; files from
spec.workspace.initialFiles are always seeded create-only.		 Replace Enum: [Replace CreateOnly]
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: {}
netbird NetBirdSpec NetBird configures NetBird overlay network integration, a self-hostable
alternative to Tailscale. At most one mesh provider (tailscale, netbird)
may be enabled per instance.		 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: {}
diskReadiness DiskReadinessSpec DiskReadiness configures an optional, opt-in defense-in-depth readiness
guard for PVC-backed workspaces. When enabled, the readiness probe is
rendered as an exec probe that also verifies the workspace volume is
writable and has free space above a threshold, so a full or read-only
PVC marks the pod NotReady (draining it from Service endpoints) instead
of silently accepting traffic it cannot persist. Liveness and startup
probes are unaffected, so a full PVC does not turn into a CrashLoopBackOff.
The application-level /readyz endpoint remains the primary readiness
signal; this guard is secondary. Defaults to disabled.		 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://paperclip.inc/docs/operators/openclaw/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 docker.io/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: {}

WorkspaceFileUpdatePolicy

Underlying type: string

WorkspaceFileUpdatePolicy controls whether a seeded workspace file converges to its source or is written only once.

Validation:

  • Enum: [CreateOnly Replace]

Appears in:

Field Description
CreateOnly WorkspaceFileUpdatePolicyCreateOnly writes the file only when the
destination does not exist. This is the backward-compatible default and
the right choice for runtime-owned workspace state.
Replace WorkspaceFileUpdatePolicyReplace rewrites the file whenever its source
content changes, so files owned by Git or another external source keep
converging.
A local edit survives until the next genuine source change: the operator
records the hash of the content it last applied, and rewrites only when
that hash moves. It never prunes a workspace directory, and never deletes
a destination because a source key was removed.

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: {}
fileUpdatePolicy WorkspaceFileUpdatePolicy FileUpdatePolicy is the default update policy for every file seeded into
this workspace. CreateOnly (the default) keeps the seed-once behavior:
once a destination file exists on persistent storage, later source
changes never replace it. Replace makes files converge whenever their
source content changes.
Per-path overrides live in ManagedFiles.		 CreateOnly Enum: [CreateOnly Replace]
Optional: {}
managedFiles ManagedWorkspaceFile array ManagedFiles declares per-path update policies, overriding
FileUpdatePolicy for the listed paths.
A path listed here is managed even if no source currently provides it, so
adding the file to a configMapRef later does not require a CR change.		 MaxItems: 50
Optional: {}