PR #76034: feat(config-ui): add basic/advanced field split and doc-link affordance

• Repository: openclaw/openclaw
• Author: symonbaikov
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/76034

Description (problem / solution / changelog)

● - [x] Add FIELD_ADVANCED set in schema.hints.ts to mark technical config fields (auth cooldowns, gateway infra knobs, diagnostics subsections, etc.) as advanced, so the config form can hide them by default

• Add docLink field to ConfigUiHint type for future per-field docs links
• In config-form.node.ts renderObject, split top-level section fields into basic (visible by default) and advanced (collapsed <details> disclosure) when no search is active; search bypasses the split so all matching fields are always visible
• Add renderHelpBlock helper that renders help text, doc link, and tags together; render the Docs ↗ anchor when hints.docLink is set
• Add CSS for .cfg-advanced-section disclosure and .cfg-field__doc-link

Summary

• Problem: The config UI shows all settings at the same level — basic toggles sit alongside low-level infra knobs (auth backoff timers, gateway health-check intervals, otel settings), making the page feel dense and hard to navigate for non-expert users.
• Why it matters: New users opening the config page see 50+ fields at once with no visual hierarchy; important settings like log level or update channel are buried next to rarely-touched tuning parameters.
• What changed: Top-level fields in each config section are now split into "basic" (always visible) and "advanced" (collapsed <details> disclosure with a count badge). The split is bypassed when a search query is active so all matching fields remain discoverable. The ConfigUiHint type gains an optional docLink field; when set, a Docs ↗ anchor is rendered inline with the help text.
• What did NOT change: Raw mode, search behavior, the Form/Raw toggle, nested-object collapsibles, tag filtering (tag:advanced), and plugin-owned channel hints are all untouched.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #75947
• This PR fixes a bug or regression

Root Cause (if applicable)

N/A

Regression Test Plan (if applicable)

N/A — feature addition, not a regression fix.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/config/schema.hints.test.ts (42 tests pass, hint building logic unchanged)
• Scenario the test should lock in: N/A
• Why this is the smallest reliable guardrail: N/A
• Existing test that already covers this (if any): src/config/schema.hints.test.ts
• If no new test is added, why not: The change is a pure rendering split in Lit templates; the split logic (hintForPath(...).advanced) is trivial and covered indirectly by existing hint-building tests.

User-visible / Behavior Changes

• Config page sections now show only "basic" fields by default; technical/tuning fields are hidden inside a collapsed "Advanced" disclosure with a count badge (e.g. "Advanced 5").
• Clicking the disclosure reveals the advanced fields in-place, consistent with existing nested-object collapsibles.
• Searching (tag:advanced, free text) bypasses the split — all matching fields appear regardless of their audience tier.
• No default values, keys, or config behavior changed.

Diagram (if applicable)

Before:
[Auth section] -> [profiles] [order] [cooldowns.*] [backoff timers...] (all flat)

After:
[Auth section] -> [profiles] [order]
                  ▸ Advanced (1)  <- collapsed by default
                    └─ [cooldowns.*] [backoff timers...]

Search active:
[Auth section] -> all matching fields visible regardless of advanced flag

Security Impact (required)

- New permissions/capabilities? No
- Secrets/tokens handling changed? No
- New/changed network calls? No
- Command/tool execution surface changed? No
- Data access scope changed? No

Repro + Verification

Environment

- OS: Linux (Fedora 43)
- Runtime/container: Node 22, local dev
- Model/provider: N/A
- Integration/channel: N/A
- Relevant config: default

Steps

1. Open the control UI → Yapılandırma (Configuration) tab
2. Navigate to the Authentication section
3. Observe that "Auth Profiles" and "Auth Profile Order" are visible by default; "Auth Cooldowns" is collapsed under "Advanced (1)"
4. Click "Advanced" disclosure → cooldown fields appear
5. Type tag:advanced in the search box → all advanced fields across all sections appear

Expected

- Basic fields visible, advanced fields collapsed by default
- Search bypasses the split and shows all matches

Actual

- Matches expected behavior

Evidence

- Failing test/log before + passing after — pnpm test src/config/schema.hints.test.ts: 42 passed

Human Verification (required)

- Verified scenarios: Basic/advanced split renders correctly; search overrides split; Form/Raw toggle unaffected; dark/light theme looks correct
- Edge cases checked: Section with zero advanced fields (no disclosure rendered); search with tag:advanced returns advanced fields across all sections
- What you did not verify: Full E2E in all locales; mobile layout

Review Conversations

- I replied to or resolved every bot review conversation I addressed in this PR.
- I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

- Backward compatible? Yes
- Config/env changes? No
- Migration needed? No

Risks and Mitigations

- Risk: A field that should be "basic" ends up in FIELD_ADVANCED (or vice versa), hiding something a user needs to find.
  - Mitigation: The search box always reveals all fields regardless of the split; no field is permanently hidden. The FIELD_ADVANCED set is a small explicit allowlist — only paths we
deliberately audited are marked.

## Changed files

- `CHANGELOG.md` (modified, +1/-0)
- `src/config/schema.hints.ts` (modified, +36/-0)
- `src/gateway/protocol/schema/config.ts` (modified, +1/-0)
- `src/shared/config-ui-hints-types.ts` (modified, +1/-0)
- `ui/src/styles/config.css` (modified, +90/-0)
- `ui/src/ui/views/config-form.advanced-split.test.ts` (added, +67/-0)
- `ui/src/ui/views/config-form.node.ts` (modified, +172/-37)
- `ui/src/ui/views/config-form.search.node.test.ts` (modified, +13/-0)