OpenClaw EnterpriseDOCSGitHub

Configuration

OpenClaw Control Plane (OCC) keeps Agent settings and platform settings in separate places. Agent settings live in a reusable Configuration in the Agent's Namespace. Saving a change does not affect a running Agent; deploy each Agent that should use it. Platform operators set Installation and Driver options in trusted startup YAML, not in Agent Configurations.

Every Agent Configuration has the required, immutable kind: "agent". Its values holds the native OpenClaw document, including env, file, and exec SecretRefs. The optional secretBindings field binds exact Namespace-owned Secrets to selected gateway environment variables; the Secret Driver stores the values separately. The Configuration Driver stores the native document. The bundled Kubernetes Driver uses one openclaw.json ConfigMap entry. Reviewed bundled and installed Configuration Drivers are available in development and production.

Installation startup configuration

Set OCC_CONFIG_PATH to the absolute path of a trusted YAML file. Production requires this setting; development can omit it to retain its existing local defaults. When provided, both API and worker processes must read the same file. The production Kubernetes deployment guide owns the complete bundled-Driver Installation example, including immutable images, workload isolation, and projected ServiceAccount credentials. The Driver package installation guide owns the installed IAM, Compute, and Configuration selection contract. The Backend reference defines the optional backend array and its required related Driver membership. Backend configuration never enters native Agent Configuration documents. The optional presets.includeDefaults boolean adds bundled Agent Presets to Namespaces; it defaults to false. See Preset initialization for permissions, restart behavior, and preservation of existing copies.

OCC resolves its persisted singleton Installation internally; Configuration and Secret Driver operations do not include Installation management. Installed Drivers remain trusted, unsandboxed controller code. Invalid production YAML, unsupported settings, and unavailable Drivers stop startup before requests run.

Each selected Driver validates its own closed configuration schema; unknown fields fail startup. OCC routes authorization through the selected IAM Driver, whose reviewed implementation is trusted to enforce its policy.

The optional observability block sets one external console destination:

yaml
observability:  url: https://grafana.example.com/d/occ-observability

url must be an absolute HTTP or HTTPS URL without embedded credentials or a fragment. Unknown fields fail startup. The API exposes the URL only after an Installation administer check; the console hides the link when unset or unauthorized. The destination handles its own authentication. This setting does not select an OpenTelemetry exporter or embed a dashboard. Compose development can use this block alone with its default Drivers; mount the same file into API and worker containers.

The optional runtime block declares a runtime image built with native worker support, which dedicated native OpenClaw requires:

yaml
runtime:  nativeWorkerSupport: custom-image

custom-image is the only value. It is off by default, and no API or Agent Configuration field can set it. When set, the Installation API reports capabilities.nativeWorkers and admission accepts dedicated native OpenClaw. Declare it only for a runtime image built from an OpenClaw source with required worker placement and native worker inference. It is unsupported with the pinned runtime image, whose Gateways and Harnesses refuse to start. See Native worker support.

Create, read, update, and delete

POST /namespaces/:namespaceId/configurations creates one reusable native Agent Configuration. A representative request body is:

json
{  "kind": "agent",  "values": {    "agents": { "defaults": { "sandbox": { "mode": "all" } } }  }}

Successful creation returns HTTP 201. The response's data contains its server-generated id, owning namespaceId, kind: "agent", initial generation: 1, unchanged values, optional secretBindings, and createdAt; meta.requestId identifies the request. Add secretBindings only after the referenced Namespace-owned Secrets exist.

OCC generates the cfg_ identifier and derives ownership from the exact route Namespace; callers cannot select either field. GET, PATCH, and DELETE operate on /namespaces/:namespaceId/configurations/:configurationId. A PATCH body requires the replacement values and may also set secretBindings, for example:

json
{  "values": {    "agents": { "defaults": { "sandbox": { "mode": "all" } } }  }}

GET and PATCH return HTTP 200; PATCH always includes a replacement values document and increments its server-managed generation exactly once, so omitted models and secrets sections disappear. Omitting secretBindings on PATCH preserves the existing bindings; send {} to clear them. PATCH cannot change or accept kind, generation, or ownership fields. Successful DELETE returns HTTP 204 with no body.

Creation requires kind: "agent"; missing or unsupported kinds are rejected. Additional consumer kinds are reserved for future approved resources and are not accepted. values must be a JSON object. It can contain the nested objects, arrays, strings, finite numbers, booleans, and nulls used by native OpenClaw configuration. OCC preserves the native document without interpreting its fields or resolving SecretRefs. Agent deployment separately validates supported runtime selection, topology, and Secret binding ownership before admission. Creation requires create permission for Configurations in the exact parent Namespace. Reads, updates, and deletes require the corresponding permission for the exact Configuration. Authentication failures return 401, malformed inputs 400, denied operations 403, missing resources 404, dependency conflicts 409, and unavailable authorization or storage 503.

Credentials and channels

Never put plaintext credentials in Configuration values. Use unresolved native SecretRefs and authorized same-Namespace Secret bindings for gateway credentials; select model credentials through Agent harnessAuth. See Configuration secrets and channels for binding permissions, complete examples, runtime delivery, and supported Slack/Teams settings.

Agent references and immutable revisions

An Agent references one Configuration in its own Namespace:

json
{  "name": "support-agent",  "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000"}

Updating the Agent can replace its configurationId; OCC rejects references outside the Agent's Namespace or to a Configuration whose kind is not "agent". Agent creation, update, and deployment separately require read permission for the exact referenced Configuration. Deployment deeply snapshots its admitted native document, including unresolved inline SecretRefs, into the immutable AgentRevision.configuration field and records configurationId, configurationKind, and configurationGeneration as separate revision fields. A selected SandboxDriver may transform a copy through configureAgent before admission; the reusable Configuration and its generation remain unchanged. The snapshot contains that effective document, and its metadata identifies the source generation. Subsequent Configuration updates do not change a running gateway or existing revision; only a later explicit deployment observes the next generation. Deleting a Configuration still referenced by an Agent returns 409.

Native OpenClaw provider settings in values.channels follow the same Configuration ownership and immutable Agent deployment lifecycle.

Database constraints require the supported Configuration kind, a positive generation, matching Agent ownership, and a valid immutable admitted revision snapshot. The native configuration document keeps its existing root-object shape without a wrapper, reserved persistence key, or reconstruction from environment-variable names. secretBindings remain separate from values so OCC can authorize, validate, and freeze delivery references without rewriting the native OpenClaw document.

AgentRevisions retain their selected Compute Driver identity and immutable Configuration snapshot. Compute runtime settings are loaded from Installation startup YAML and are not copied into that snapshot. See the Agent revision contract for the fields admission freezes; immutable Configuration does not freeze all Driver settings.

Kubernetes storage

The Kubernetes Configuration Driver stores live native documents in tenant ConfigMaps. Compute creates separate immutable revision snapshots. See Kubernetes Configuration storage for placement, readiness, ownership, and exact RBAC requirements.

Failure semantics and limitations

Search documentation