Agent Section UI Regression in v2 Interface

Primary Visual Degradations

• Agent List Transform: The interactive agent selection UI changed from a styled list/card grid to a bare-bones dropdown selector, eliminating visual hierarchy and selection affordance.
• Missing Agent Emoji: All agent emojis are absent from both the selection interface and info display panels. Previously rendered as visual identifiers, they no longer appear.
• Text Contrast Failure: Labels and content exhibit poor contrast ratios against backgrounds, causing legibility issues. Font sizing appears inconsistent or incorrectly scaled.
• Non-functional Overflow Menu: The "..." button in the agent section renders but triggers no action, indicating a disconnected event handler or removed functionality.
• Model Selector Breakage: Model selection controls remain broken in the v2 interface, failing to update or persist user selections.

CLI Context Check

# Verify OpenClaw version experiencing UI regression
openclaw --version
# Expected: 3.12.x or 3.13.x

# Check UI mode activation
OPENCLAW_UI=v2 openclaw ui
# Observe: Dropdown instead of list, missing emojis

# Alternative: Check via browser DevTools console
# window.__OPENCLAW_VERSION__ // Should show 3.12+
# document.querySelectorAll('.agent-item').length // Returns 0 or unexpected count

Architectural Divergence

The v2 UI introduced a complete rewrite of the agent selection component, migrating from a custom card-based React component to a standard HTML <select> dropdown. This architectural decision caused several cascading failures:

1. Emoji Rendering Elimination

The dropdown implementation uses native browser select elements, which do not support rich content rendering (emoji, images, custom styling). The previous AgentCard component explicitly rendered emoji via:

// Legacy code pattern (removed)
<div className="agent-emoji">{agent.emoji}</div>
<span className="agent-name">{agent.name}</span>

// v2 replacement (broken)
<select>
  <option value={agent.id}>{agent.name}</option>
</select>

2. CSS Styling Scope Regression

The v2 component inherits default browser dropdown styling instead of applying the custom OpenClaw theme variables. CSS classes targeting .agent-card are no longer referenced by new markup.

3. Event Handler Disconnection

The "..." overflow menu trigger lost its onClick binding during the component rewrite. The handler was likely tied to a removed context menu or modal that was not migrated to the new architecture.

4. State Management Breakage

Model selector failures stem from mismatched state key names between the v2 store slice and the component props:

// v1 state path
state.agents.selectedModel

// v2 state path (broken reference)
state.agentConfig.modelId

Option A: Revert to Compatible UI Version

If immediate functionality is required without waiting for a fix:

# Force legacy UI mode (if supported)
export OPENCLAW_UI_MODE=legacy
openclaw ui

# Or specify version flag
openclaw ui --ui-version=1

Option B: Hotfix via Configuration Override

If the v2 component supports theme overrides:

# Add to openclaw.config.js
module.exports = {
  ui: {
    agentSection: {
      useLegacyComponents: true
    }
  }
}

Option C: CSS Override for Contrast

Emergency styling fix via browser extension or injected stylesheet:

/* Create custom-theme.css */
.agent-section select {
  background: #1a1a2e !important;
  color: #e8e8e8 !important;
  font-size: 14px !important;
  border: 1px solid #3a3a5a !important;
  padding: 8px 12px !important;
}

.agent-section select option {
  background: #1a1a2e !important;
  color: #ffffff !important;
}

.agent-section .overflow-btn {
  opacity: 0.5;
  pointer-events: none !important;
}

Option D: Disable v2 UI Entirely

# Via environment variable
echo "OPENCLAW_DISABLE_V2_UI=1" >> ~/.openclaw/env

# Or via CLI flag
openclaw ui --disable-v2

After applying any fix, verify the agent section renders correctly:

# 1. Launch UI with monitoring
openclaw ui --debug 2>&1 | grep -i "agent"

# 2. Check browser console for component mount
# DevTools > Console:
# > document.querySelector('.agent-section')?.className
# Expected: "agent-section card-grid" (not "agent-section dropdown")

# 3. Verify emoji presence
# DevTools > Console:
# > document.querySelectorAll('.agent-item').length
# Expected: > 0
# > document.querySelector('.agent-item')?.textContent
# Expected: Contains emoji character

# 4. Test overflow button functionality
# > document.querySelector('.overflow-btn')?.onclick
# Expected: Function (not null)

# 5. Test model selector
# 1. Click model dropdown
# 2. Select different model
# 3. Verify selection persists after navigation
# Expected: Model selection retained

Expected UI State After Fix

• Agent list renders as clickable cards/grid items
• Each agent displays emoji prefix (e.g., "🤖 Agent Name")
• Text contrast ratio exceeds WCAG AA (4.5:1 minimum)
• "..." button opens context menu or dropdown
• Model selector updates state correctly

• Browser Cache: After applying CSS overrides, clear browser cache or use hard refresh (Ctrl+Shift+R) to ensure new styles load. The v2 UI bundle may be cached aggressively.
• Config File Locations: Ensure config overrides are placed in the correct project directory, not a parent directory. OpenClaw searches ./openclaw.config.js before ~/.openclaw/.
• Version Mismatch: Some UI flags are version-gated. Running openclaw ui --ui-version=legacy on v3.12 may have no effect if that flag was introduced in v3.14+. Verify flag existence with openclaw ui --help.
• Docker Environment: If running via Docker, environment variables must be passed with -e flags:

  docker run -e OPENCLAW_DISABLE_V2_UI=1 openclaw/ui:latest

• WSL/Windows Path Issues: On WSL2, config file watchers may fail silently. Use absolute paths in configuration rather than relative paths.
• Model Selector State: The model selector bug may persist even after UI fixes if the underlying state slice is not migrated. Check browser DevTools > Redux DevTools (if installed) to verify state paths match component subscriptions.

• ERR_UI_COMPONENT_NOT_MOUNTED — Occurs when accessing agent controls before v2 UI fully initializes; may manifest as "..." button click producing no output.
• WARN_STALE_STATE_KEY — Logged when component reads deprecated state path (agents.selectedModel) that v2 store no longer populates.
• Issue #847 — Model selector resets on page refresh — Related state persistence failure in v2 interface.
• Issue #891 — Dropdown styling breaks on Safari — Cross-browser dropdown rendering inconsistency.
• Issue #912 — Agent emoji missing in notifications — Broader emoji rendering regression across UI components.
• Issue #856 — v2 UI loads 3x slower than legacy — Performance regression warning; may indicate bundle bloat from new component dependencies.

If experiencing multiple related errors, consider downgrading to v3.11.2 which maintained stable agent section UI:

# Install specific stable version
npm install -g [email protected]

# Verify installation
openclaw --version  # Should output: 3.11.2