openclaw - 💡(How to fix) Fix [Bug]: Control UI inconsistently handles workspace-relative agent avatars even when /avatar/{agentId} resolves correctly [1 comments, 1 participants]

Bug type

Behavior bug (incorrect output/state without crash)

Summary

Control UI / WebChat does not consistently handle workspace-relative identity.avatar values from IDENTITY.md.

A workspace-relative avatar such as:

- **Avatar:** avatars/懂王.jpg

is documented/schematically valid and is correctly resolved by the backend, but some Control UI rendering paths ignore it and fall back to the default avatar/logo instead of using the resolved /avatar/<agentId> route.

This looks like a frontend compatibility/regression issue in 2026.4.22 rather than a backend/avatar-serving failure.

Steps to reproduce

1. In the agent workspace IDENTITY.md, set a workspace-relative avatar path, for example:

   - **Avatar:** avatars/test-avatar.jpg

2. Ensure the file exists in the workspace and is a valid image.
3. Start/restart Gateway normally.
4. Open Control UI / WebChat.
5. Observe that some UI locations still show the default avatar/logo instead of the configured agent avatar.

Expected behavior

All Control UI / WebChat assistant-avatar surfaces should consistently display the configured agent avatar when identity.avatar is set to a valid workspace-relative path.

In particular, if the backend can already resolve the avatar through /avatar/<agentId>, frontend rendering should use that resolved route consistently instead of rejecting the original workspace-relative string.

Actual behavior

The backend resolves and serves the avatar correctly, but some frontend paths still render the default avatar/logo.

Observed facts from local verification on 2026.4.22:

• IDENTITY.md contained:

  - **Avatar:** avatars/懂王.jpg

• The image file existed and was valid.
• GET /avatar/main?meta=1 returned:

  {"avatarUrl":"/avatar/main"}

• GET /avatar/main returned 200 image/jpeg.
• The bytes served by /avatar/main matched the configured workspace file exactly (SHA-256 matched).

So the failure is not:

• a missing file
• a bad workspace-relative path
• a broken avatar endpoint
• a failed upgrade

It appears to be a frontend rendering inconsistency.

Why this looks like a frontend bug

From inspection of the built Control UI bundle in 2026.4.22:

• One code path correctly fetches /avatar/<agentId>?meta=1 and then /avatar/<agentId>.
• But other code paths read identity.avatarUrl / identity.avatar directly and only accept values matching data:image/... or paths starting with /.
• A workspace-relative value like avatars/懂王.jpg therefore gets rejected by those frontend branches, even though the backend supports it and exposes /avatar/main correctly.

In other words:

• backend behavior: correct
• documented config style: correct
• frontend handling: inconsistent across UI branches

Docs / schema consistency note

This format appears intended/supported:

• Docs template includes examples like workspace-relative avatar paths.
• Runtime schema includes agents.list[].identity.avatar.

That makes the current behavior especially confusing, because the configured value is valid and the backend honors it.

OpenClaw version

2026.4.22

Operating system

macOS (arm64)

Install method

npm global

Model

Not model-related

Additional information

Related issues that may be adjacent but seem not identical:

• #70166 — Control UI avatar broken after upgrade from v4.14 to v4.21
• #53610 — Avatar endpoint /avatar/{agentId} returns 404
• #17298 — Control UI should display configured agent avatars instead of default favicon

This report is narrower:

/avatar/main works correctly, but some Control UI rendering paths still ignore a valid workspace-relative identity.avatar and fall back to the default avatar.

Suggested fix direction

Control UI should normalize all assistant-avatar rendering to one consistent source of truth, preferably the resolved /avatar/<agentId> route (or an equivalent resolved URL), instead of directly validating raw identity.avatar strings in some branches and resolved avatar URLs in others.