Agent Chat UX

agent-chat-ux

name: agent-chat-ux
version: 1.4.0
author: Charles Sears
description: Multi-agent UX for OpenClaw Control UI — agent selector, per-agent sessions, session history viewer with search, agent-filtered Sessions tab with friendly names, Create Agent wizard, emoji picker, and backend agent CRUD.

⚠️ Security & Transparency Notes

Before applying this skill's patches, be aware of the following:

Credential Access (agents.wizard)

The AI Wizard backend (agents.wizard RPC) calls the configured model provider API directly via HTTP. To do this it needs an API key. It resolves credentials in this exact order:

1. Default config auth — uses it if the resolved mode is api-key (most common)
2. Auth profile store — searches for the first api_key-type profile matching the provider. Reads only provider and type fields to find it; does not log or return values.
3. Environment variable — ANTHROPIC_API_KEY or OPENAI_API_KEY as a last resort

If you don't want the wizard reading your auth store, set ANTHROPIC_API_KEY in your environment and ensure your default auth profile is already api-key mode — step 2 is skipped entirely in that case.

External API Calls

agents.wizard makes a single HTTP POST to:

• https://api.anthropic.com/v1/messages (Anthropic models)
• https://api.openai.com/v1/chat/completions (OpenAI-compatible models)

No other outbound calls. The call carries your user-supplied description and nothing else from your system.

Patch Scope

These patches modify only agent-related files:

Each patch is scoped to a single concern. If any patch file modifies more than the files listed above, stop — you have an outdated copy.

LLM Output Validation

Wizard model output is parsed as JSON and validated before use:

• Must be a JSON object with name (string), emoji (string), soul (string)
• name is capped at 100 characters, emoji at 10
• soul must be ≥ 20 characters
• Empty or non-JSON responses are rejected with a user-visible error — nothing is auto-created

Source Code Modification

This skill applies git apply patches against ~/openclaw and requires a UI + gateway rebuild. Changes are persistent. Always backup before patching:

cd ~/openclaw && git stash  # or git branch backup/pre-agent-ux

What This Skill Adds

1. Agent Selector Dropdown in Chat Header

When multiple agents are configured, a dropdown appears left of the session dropdown in the chat header. Selecting an agent switches to that agent's most recent session (or falls back to a fresh webchat key for that agent). The session dropdown automatically filters to show only sessions belonging to the selected agent.

2. Per-Agent Session Filtering (Sorted Newest First)

Sessions are now scoped to the active agent and sorted newest-first. No more mixing other agents' cron jobs and subagent sessions into the current chat's session picker.

3. + New Session Button in Chat Header

A + icon button sits right of the session dropdown, allowing new sessions to be started without typing /new.

4. Create Agent Panel (Manual + AI Wizard)

The Agents tab gains a + Create Agent button that expands a panel with two modes:

Manual mode:

• Agent name
• Workspace path (auto-generated from name if left blank)
• Emoji picker (see below)

AI Wizard mode:

• Describe the agent in plain English
• Click "Generate Agent" — AI generates name, emoji, and full SOUL.md
• Review the preview, then click "✅ Create This Agent"

After creation, the agents list and config form are both refreshed automatically — no "not found in config" error, no manual reload needed.

5. Emoji Picker Dropdown

The emoji field in Create Agent and Edit Agent forms is a dropdown with 103 curated emojis grouped into 5 categories (Tech & AI, People & Roles, Animals, Nature & Elements, Objects & Symbols), each showing the emoji and its name. A large live preview shows the selected emoji next to the dropdown.

6. Edit Agent Inline (Agents Overview)

The Agents Overview card now shows editable inputs directly — no toggle needed:

• Name, Emoji (dropdown, 103 emojis), Workspace are always editable
• Changes activate the bottom Save button — no separate inline Save/Cancel
• Emoji is saved as - Emoji: in IDENTITY.md (last-wins override of creation value); identity cache is evicted after save so changes appear immediately
• Edit uses the emoji param of agents.update (not avatar) so the correct IDENTITY.md key is written

7. Delete Agent

• 🗑️ Delete button appears in the Overview header for non-default agents
• Inline confirmation dialog before deletion; hidden for the main/default agent

8. Agent-Specific Cron Stats

The Scheduler card on the Cron Jobs tab previously showed global gateway stats (total job count, global next wake). Now:

• Jobs → count of cron jobs targeting this agent only
• Next wake → earliest nextRunAtMs across this agent's jobs (n/a if no jobs)
• Subtitle → "Agent cron scheduling status." (was "Gateway cron status.") This means agents with no crons correctly show Jobs: 0 / Next wake: n/a.

9. Agents Tab — Model Selector Cleanup

• Removed the redundant read-only "Primary Model" row from the Overview grid (it's already editable in the Model Selection section below)
• Fallback models converted from a free-text comma-separated input to a proper <select multiple> using the same full model catalog as the primary selector
• Added spacing and clear labels between primary and fallback fields
• Small hint "(hold Ctrl/⌘ to select multiple)" on the fallback selector

10. Backend — agents.create / agents.update / agents.delete / agents.wizard

New RPC handlers wired into the gateway:

Auth fix in agents.wizard: Raw HTTP calls to the model API require an api_key token, not an OAuth/bearer token. The wizard now falls back to an explicit api_key profile (or ANTHROPIC_API_KEY env var) when the default resolved auth mode is oauth or token.

11. Session History Viewer (v1.4.0)

A modal overlay accessible from the Sessions tab that displays full conversation history for any session:

• Agent dropdown filter — scope sessions by agent
• Session dropdown — pick a session to view (filtered by agent)
• Search bar — debounced full-text search across message content (case-insensitive)
• Role filter chips — All / User / Assistant / System / Tool
• Message timeline — role icons (👤/🤖/⚙️/🔧), timestamps, and message text
• Pagination — "Load More" with count display (100 messages per page)
• Click "History" button on any row in the Sessions tab to open

12. Sessions Tab Overhaul (v1.4.0)

The Sessions tab now provides a unified multi-agent experience:

• Agent filter dropdown — filter sessions by agent (populated from agents.list)
• Friendly session names — "Main Session", "Cron: pipedream-token-refresh", "discord:#bot-chat" instead of raw keys like agent:main:cron:cc63fdb3-...
• Agent identity column — shows agent emoji + identity name (e.g. "🤖 Assistant") using identity.name → name → id fallback chain
• Raw key shown as subtitle — full technical key displayed in smaller muted monospace text below the friendly name
• Label column removed — redundant since the friendly name already incorporates label/displayName
• CSS grid layout — proper column alignment using grid-template-columns with proportional widths; headers align precisely with data
• Empty state — clear message when an agent has no sessions
• Session count — total/filtered count shown in the store info line
• History button pre-selects — clicking History on a row opens the modal with agent and session already selected, loading history immediately

13. Backend — sessions.history RPC (v1.4.0)

New RPC handler that reads full JSONL transcript files:

Returns {key, sessionId, agentId, total, offset, items[{role, text, timestamp}]}.

Files Changed

UI Design & Styling Reference

This section documents the UI design decisions for anyone installing or extending this skill.

Sessions Tab Layout

Uses CSS grid (display: grid) instead of the default OpenClaw .table flex layout for precise column alignment:

.sessions-grid {
  grid-template-columns: 2fr 1.2fr 0.6fr 0.8fr 1fr 0.8fr 0.8fr auto;
  /* Session | Agent | Kind | Updated | Tokens | Thinking | Reasoning | Actions */
}

• Headers: 12px uppercase, letter-spacing 0.5px, var(--text-muted) color, bottom border
• Rows: display: contents for grid participation, subtle bottom border, hover highlight at 2% white opacity
• Session name cell: Friendly name as bold link (var(--accent, #6366f1)), raw key below in 11px muted monospace at 50% opacity
• Agent column: 13px text, emoji + identity name (e.g. "🤖 Assistant")
• Selects: max-width: 100px to prevent overflow

Session History Modal

Dark overlay modal with the following structure:

┌──────────────────────────────────────────────────┐
│  Session History                            [✕]  │
│  [Agent ▼]  [Session ▼]                         │
│  [🔍 Search...]  [All] [User] [Asst] [Sys] [Tool]│
│  ─────────────────────────────────────────────── │
│  👤 User · Feb 23, 10:23 AM                     │
│  Hello, can you help me?                         │
│  ─────────────────────────────────────────────── │
│  🤖 Assistant · Feb 23, 10:23 AM                │
│  Of course! What do you need?                    │
│  ─────────────────────────────────────────────── │
│          [Load More ↓]  Showing 100 of 342       │
└──────────────────────────────────────────────────┘

Key CSS variables used:

• var(--bg-card, #1a1a2e) — modal background
• var(--border, #333) — borders
• var(--accent, #6366f1) — user role color, active chip
• var(--text, #e0e0e0) — message text
• var(--border-subtle, rgba(255,255,255,0.06)) — message separators

Role colors:

Role icons: 👤 User, 🤖 Assistant, ⚙️ System, 🔧 Tool, 💬 Other

Session Name Resolution

The friendly name fallback chain:

1. row.label (user-set label)
2. row.displayName (server-computed, e.g. "discord:#bot-chat")
3. Smart key parsing:
   • *:main → "Main Session"
   • *:cron:*:run:* → "Cron Run"
   • *:cron:* → "Cron Job"
   • *:subagent:* → "Subagent"
   • *:openai:* → "OpenAI Session"
   • *:<channel>:direct:<id> → "Channel · id"
   • *:<channel>:group:* → "Channel Group"
4. Raw key as fallback

Agent Identity Resolution

For the Agent column and dropdowns:

1. agent.identity.name (from IDENTITY.md — e.g. "Assistant")
2. agent.name (from config — e.g. "main")
3. agent.id (raw identifier)

Emoji: agent.identity.emoji with "🤖" as fallback.

Chat Dropdown

The session dropdown in the chat header shows all sessions for the selected agent (no time filter). Previously limited to sessions active within 120 minutes, which hid older Discord channels and other sessions.

Installation

This skill requires patching OpenClaw source files and a UI + gateway rebuild.

Prerequisites

• OpenClaw source at ~/openclaw (fork or local clone)
• pnpm installed (npm install -g pnpm)
• Node.js 20+

Step 1: Apply patches

cd ~/openclaw

git apply ~/.openclaw/workspace/skills/agent-chat-ux/references/schema-agents.txt
git apply ~/.openclaw/workspace/skills/agent-chat-ux/references/agents-view.txt
git apply ~/.openclaw/workspace/skills/agent-chat-ux/references/agents-utils.txt
git apply ~/.openclaw/workspace/skills/agent-chat-ux/references/agents-panels-cron.txt
git apply ~/.openclaw/workspace/skills/agent-chat-ux/references/app-render-helpers.txt
git apply ~/.openclaw/workspace/skills/agent-chat-ux/references/app-render.txt
git apply ~/.openclaw/workspace/skills/agent-chat-ux/references/app-main.txt
git apply ~/.openclaw/workspace/skills/agent-chat-ux/references/server-agents.txt

If any patch fails due to upstream drift, apply manually using the patch file as a line-by-line reference.