OpenClaw EnterpriseDOCSGitHub

Configuration Driver and Agent Revision Flow

Overview

The OCC API and worker load trusted, singleton Installation settings from startup YAML and validate each selected Driver before construction. Authenticated API requests then create, read, replace, or delete exact Namespace-owned native OpenClaw configuration documents through the selected bundled or installed Configuration Driver. The bundled Kubernetes implementation persists each document in a tenant-owned ConfigMap. Each Configuration requires immutable kind: "agent" and a server-managed generation; documents preserve unresolved inline SecretRefs without interpreting them. Agent deployment authorizes the separate Secret bindings, applies any selected Sandbox Driver transformation, and freezes the admitted values into an immutable AgentRevision. Configuration identity, kind, generation, and Secret references are recorded separately. This flow stops when OCC persists that revision and hands off workload reconciliation; the selected Compute Driver then owns the Agent gateway, while worker execution and secret resolution remain outside this flow's scope.

Entry Points

Flow

graph TD
  A["API or worker startup"] -->|reads absolute path| B["Trusted Installation YAML"]
  B --> C{"Closed Driver schemas valid?"}
  C -->|no| X["Reject startup"]
  C -->|yes| D["Construct selected Compute and Configuration Drivers"]
  D --> E["Resolve singleton Installation and construct IAM"]
  E --> G["Accept exact Namespace Configuration request"]
  G --> H{"IAM authorizes exact resource?"}
  H -->|no| Y["Reject without cross-Namespace access"]
  H -->|yes| I["Lock PostgreSQL ownership metadata"]
  I --> J["Validate agent kind and generation; invoke the selected Configuration Driver"]
  J --> K{"Agent deployment references Configuration?"}
  K -->|no| L["Return authorized Configuration response"]
  K -->|yes| M["Authorize and lock exact Configuration"]
  M --> P["Authorize Secret bindings and verify backend references"]
  P --> Q["Apply optional Sandbox transform; validate configuration and Harness"]
  Q --> N["Freeze admitted values, Configuration metadata, and Secret references"]
  N --> O["Hand off admitted revision to reconciliation"]

Execution Trace

1. Construct the selected Installation Configuration Driver

apps/controller/src/composition/installation-config.ts:loadInstallationConfiguration

The API and worker load trusted Installation selections and validate the chosen Configuration Driver's schema and implementation-owned rules before constructing its bundled or installed implementation. OCC receives that exact capability and identity; invalid settings or a mismatched factory reject startup. Installation settings never come from a Configuration Driver. The Driver package loading flow owns package identity, validation, trust boundaries, and IAM construction.

2. Resolve singleton state and select Drivers

apps/controller/src/composition/production.ts:composeProduction

Production composition loads the sole persisted Installation from PostgreSQL platform state. The API and worker load the same trusted startup document and persisted Installation identity. The Driver loading flow traces process-local construction and the selected Secret, Sandbox, and ServiceAccount branches. Existing AgentRevisions retain their selected Compute identity and immutable admitted configuration; subsequent Configuration edits apply only to later deployments.

Provisioning's KubernetesConfigurationDriver.createExact and inspectExact use the same verified CP namespace as ordinary Configuration CRUD. Recovery checks the exact identity and document there; an adopted data-plane namespace does not change canonical Configuration ownership.

3. Authorize the exact Namespace Configuration operation

packages/occ/src/index.ts:OpenClawController.createConfiguration

Configuration route contracts are dispatched by the controller request handler to OpenClawController.createConfiguration, getConfiguration, updateConfiguration, or deleteConfiguration in OCC. OCC resolves server-owned Namespace identity and checks the selected IAM Driver before touching tenant data: creation targets the exact Namespace-owned Configuration resource; reads, updates, and deletes target the exact Configuration identifier in that Namespace. Creation requires kind: "agent" and a native root-object JSON document; omitted or unknown kinds and malformed request shapes fail with 400. Updates require the complete replacement values document and accept optional secretBindings; kind, generation, and ownership are server-owned and cannot be supplied or changed. OCC preserves nested values and SecretRefs unchanged. Malformed, generation-mismatched, or ownership-invalid persisted ConfigMaps fail with 503. Authorization denial fails with 403, a missing exact resource with 404, an Agent dependency conflict with 409, and unavailable IAM or storage with 503. OpenClaw resolves inline SecretRefs at runtime; Configuration CRUD preserves them in values. OCC separately authorizes operate on each Secret selected by secretBindings, including retained bindings when PATCH omits the field. Omission preserves bindings; {} clears them. The Configuration reference owns the binding contract, and the Secret flow traces storage and delivery. Secret Broker substitution remains unimplemented.

4–5. Persist Configuration and freeze its revision

Configuration persistence and revision snapshots traces metadata locking, Driver effects, Agent reference resolution, and snapshot validation after request authorization.

Debugging and Verification

Run focused Configuration conformance and integration checks:

bash
node --test tests/conformance/configuration-occ.test.mjs tests/conformance/kubernetes-configuration.test.mjsnode --test tests/integration/configuration-controller.test.mjs tests/integration/postgres-platform-state.test.mjsnode --test tests/integration/postgres-platform-state-kubernetes.test.mjs

PostgreSQL integration requires configured database URLs; skipped cases do not prove live persistence. Live ConfigMap and least-privilege RBAC proof requires a disposable Kubernetes cluster and tenant credentials; client fixtures do not replace that evidence. Startup emits structured startup-error or worker.startup-error events for invalid YAML and unavailable dependencies. Verify missing or unknown kinds are rejected, creation starts at generation 1, updates advance it once without permitting a kind change, requests preserve the exact native document and inline references, and ConfigMaps store exactly one openclaw.json entry. Verify denials against exact Namespace and Configuration identity. Prove snapshot safety by changing a nested Configuration value after deployment and confirming the prior AgentRevision's native document, Configuration identity, kind, and generation remain unchanged while a later deployment observes the new generation. Verify same-Namespace Agents receive separate gateways only when an eligible development worker prepares their revisions. Kubernetes conformance verifies immutable Agent-owned configuration projection without a live cluster; dedicated-cluster coverage of the changed projection remains unverified when its optional integration is skipped.

Search documentation