Skip to content

ADR-0001-config-surface-unification.md

Latest commit

 

History

History
63 lines (46 loc) · 2.67 KB

ADR-0001-config-surface-unification.md

File metadata and controls

63 lines (46 loc) · 2.67 KB

ADR-0001: Configuration Surface Unification

  • Status: Accepted
  • Date: 2026-03-07
  • Owners: OpenClaw maintainers
  • Related roadmap items: R139, phase-2 follow-up completed 2026-03-19

Context

OpenClaw currently has distributed configuration logic across config.py, services/runtime_config.py, and selected call sites that still read env vars directly. This increases precedence drift risk and makes behavior harder to reason about.

The unification work required a phased, backward-compatible rollout rather than a single destructive rewrite.

Decision

Adopt one authoritative layered model for runtime LLM config resolution, exposed through a unified resolver and then through a single effective-config facade consumed by compatibility APIs and downstream readers.

Layer precedence (highest to lowest):

  1. env (OPENCLAW_* first, MOLTBOT_* fallback)
  2. runtime_override (in-memory only; process-local)
  3. persisted (OPENCLAW_STATE_DIR/config.json)
  4. default

Key points:

  • Keep env-first semantics for operational safety and backward compatibility.
  • Preserve legacy key support with explicit warning behavior.
  • Keep runtime overrides non-persisted and source-attributed.

Consequences

Positive:

  • Deterministic precedence and source attribution.
  • Reduced duplicated merge logic in primary runtime paths.
  • Safer phased migration with compatibility facade intact.
  • Shared read seams make parity testing and future deprecation work narrower.

Trade-offs:

  • Temporary coexistence of migrated and non-migrated call sites during phased rollout.
  • Additional adapter code until follow-up phases complete.

Rollout Plan

Phase 1 (R139):

  • Introduce unified resolver + runtime override registry.
  • Refactor services/runtime_config.py effective-read path to resolver-backed flow.
  • Migrate core LLM call sites to stop duplicating env precedence.
  • Add precedence/compatibility regression tests.

Phase 2 (completed 2026-03-19):

  • Introduced services/effective_config.py as the supported effective-config read facade.
  • Migrated remaining mixed-path readers touched by the phase onto the shared facade/compatibility shims.
  • Added parity coverage so env/runtime/persisted/default precedence is asserted once at the shared seam instead of at each consumer.

Future follow-ups:

  • Continue migrating any remaining direct env readers that still overlap with the runtime config contract.
  • Remove obsolete adapter/shim code once migration reaches stable completion.

Rejected Alternatives

  1. Big-bang rewrite of all config readers:
    • Rejected due to blast radius and rollback difficulty.
  2. Keep dual systems and patch ad hoc:
    • Rejected due to ongoing precedence drift and maintenance cost.