mirror of
https://github.com/rookiestar28/ComfyUI-OpenClaw.git
synced 2026-08-14 00:48:07 +00:00
64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# 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.
|