From 7519eb0efd8e93191012a656c8b06fae4b16109f Mon Sep 17 00:00:00 2001 From: rookiestar28 Date: Thu, 19 Mar 2026 20:51:11 +0800 Subject: [PATCH] docs: record recent hardening updates --- README.md | 12 ++++++++++++ .../adr/ADR-0001-config-surface-unification.md | 18 ++++++++++++------ docs/frontend_ux_walkthrough.md | 8 +++++++- docs/r69_ui_framework_migration_decision.md | 3 +++ 4 files changed, 34 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 940d559..0af3fa7 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,18 @@ Deployment profiles and hardening checklists:
+Planning, startup/config hardening, compatibility governance, and frontend hotspot reduction batch + +- Normalized the active planning surface onto `.planning/roadmap.md` and clarified the docs-only test-flow exemption in the project SOP guidance. +- Hardened route/bootstrap registration around a declarative manifest and centralized validation seam so startup wiring is less fragile under delayed readiness and import-order edge cases. +- Completed the next config-unification pass around one effective-config read facade, reducing precedence drift across backend and frontend-facing config consumers. +- Centralized legacy compatibility handling for backend headers and frontend API/storage fallbacks so deprecation behavior is explicit, shared, and regression-covered. +- Split the frontend shell hotspot and LLM model-list helper logic into smaller seams, then fixed the timer-binding regression uncovered during full-gate Playwright validation. + +
+ +
+ Private-host LLM SSRF contract clarified across Remote Admin, docs, and deployment guidance - Clarified that `OPENCLAW_LLM_ALLOWED_HOSTS` only extends the exact public-host allowlist for custom LLM `base_url` values and does not permit private/reserved LAN targets by itself. diff --git a/docs/adr/ADR-0001-config-surface-unification.md b/docs/adr/ADR-0001-config-surface-unification.md index c3ae957..fc791b4 100644 --- a/docs/adr/ADR-0001-config-surface-unification.md +++ b/docs/adr/ADR-0001-config-surface-unification.md @@ -1,19 +1,19 @@ -# ADR-0001: Configuration Surface Unification (R139) +# ADR-0001: Configuration Surface Unification - Status: Accepted - Date: 2026-03-07 - Owners: OpenClaw maintainers -- Related roadmap item: `R139` +- 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. -`R139` requires a phased, backward-compatible unification, not a single destructive rewrite. +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 consumed by `services/runtime_config.py` compatibility APIs. +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) @@ -32,6 +32,7 @@ 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. @@ -45,8 +46,13 @@ Phase 1 (`R139`): - Migrate core LLM call sites to stop duplicating env precedence. - Add precedence/compatibility regression tests. -Phase 2+ (future follow-ups): -- Continue migrating remaining direct env readers where they overlap with runtime config contract. +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 diff --git a/docs/frontend_ux_walkthrough.md b/docs/frontend_ux_walkthrough.md index 0da2bd6..95214fc 100644 --- a/docs/frontend_ux_walkthrough.md +++ b/docs/frontend_ux_walkthrough.md @@ -5,12 +5,18 @@ This document summarizes the current OpenClaw sidebar UI structure and how to ve ## UI Structure - Entry: `web/openclaw.js` registers the extension and sidebar tab. -- Shell: `web/openclaw_ui.js` renders the header, tab bar, and tab panes. +- Shell: `web/openclaw_ui.js` now acts as the composition root for the sidebar shell and public singleton exports. +- Actions: `web/openclaw_actions.js` owns submit/cancel/retry wiring and guarded action routing for the shell. +- Queue monitor: `web/openclaw_queue_monitor.js` owns queue polling lifecycle and transient banner/status updates used by the shell. - Tabs: `web/openclaw_tabs.js` manages tab registration, rendering, and remount safety. - API: `web/openclaw_api.js` provides a normalized fetch wrapper and OpenClaw endpoints (legacy Moltbot endpoints still work). - Styles: `web/openclaw.css` provides shared design tokens and component classes. - Errors: `web/openclaw_utils.js` provides `showError()` / `clearError()` helpers. +Refactor note: +- `web/openclaw_ui.js` should stay focused on shell composition, shared singleton ownership, and exports. +- New shell behaviors should prefer the extracted action/queue modules unless they truly belong to top-level shell assembly. + ## Feature Gating (Capabilities) - Backend exposes `GET /openclaw/capabilities` (legacy `/moltbot/capabilities` still works). diff --git a/docs/r69_ui_framework_migration_decision.md b/docs/r69_ui_framework_migration_decision.md index c74185e..f5557cc 100644 --- a/docs/r69_ui_framework_migration_decision.md +++ b/docs/r69_ui_framework_migration_decision.md @@ -11,6 +11,8 @@ - Entry/shell/tabs architecture: - `web/openclaw.js` - `web/openclaw_ui.js` + - `web/openclaw_actions.js` + - `web/openclaw_queue_monitor.js` - `web/openclaw_tabs.js` - Runtime model: - Loaded as a ComfyUI extension in the host page (no standalone SPA bootstrap). @@ -63,6 +65,7 @@ Scored 1-5 (higher is better), weighted by current risk profile: 1. OpenClaw frontend is host-coupled to ComfyUI extension lifecycle and remount behavior; framework migration introduces significant integration and lifecycle risk with limited near-term operator value. 2. Current architecture already has critical stability controls (`ErrorBoundary`, tab remount safety, capability-gated registration, compatibility aliases, Vitest + Playwright lanes). + Recent decomposition work also reduced shell hotspot size without introducing a framework dependency. 3. Most remaining roadmap priorities are functionality/security features (`F53/F54/F58/F59`), not frontend rendering abstraction gaps; migration now would consume high-risk bandwidth with weak ROI. ## Decision