openclaw - 💡(How to fix) Fix Expose `role` field on agent records via CLI and gateway

Problem

openclaw agents list --json currently exposes id, name, identityName, identityEmoji, workspace, agentDir, model, bindings, isDefault — but no role field.

A "role" here means a short label describing what the agent does in the operator's mental model — e.g. "UX Auditor", "Code Reviewer", "Mission Strategist", "Operations". This is distinct from identityName (the agent's persona/display name) and from model (its LLM).

Motivation

We're building AK Mission Control, a frontend dashboard on top of OpenClaw. The architectural principle is that MC reads from OpenClaw and does not mirror state OpenClaw owns.

Today, because OpenClaw doesn't surface a role, MC is forced to keep an AgentState.role column in its own SQLite DB just to render "Code Reviewer" under each agent card. That is a clear mirror-state violation — MC has to write into its own DB on every agent create/edit just to remember a string that conceptually belongs to the agent definition.

Any other OpenClaw frontend (existing dashboard, future TUI panels, third-party integrations) will hit the same wall and will end up duplicating the same field in their own stores. Putting role upstream eliminates that duplication for everyone.

Proposed shape

1. Config: optional top-level role: string field on each agent record in ~/.openclaw/openclaw.json, alongside identityName/identityEmoji.
2. CLI: surface it in openclaw agents list --json output and accept it on openclaw agents add / openclaw agents set-identity (or a new set-role).
3. Gateway: include role in the agents.list RPC response.

Example JSON output after the change:

{
  "id": "ux-auditor",
  "identityName": "UX/UI Auditor",
  "identityEmoji": "🔍",
  "role": "UX Auditor",
  "model": "deepseek/deepseek-v4-flash",
  ...
}

Alternative source

If you'd rather not add a config field, role could live in each agent's IDENTITY.md frontmatter or workspace metadata (~/.openclaw/agents/<id>/agent/identity.json), as long as it's surfaced consistently in the CLI/gateway output. Either works for our use case; the key is that it's exposed by OpenClaw so frontends don't have to keep a parallel column.

Out of scope

• Not asking for role-based access control / authorization. This is purely a descriptive label.
• Not asking for a fixed enum of roles. Free-form string is fine.

Acceptance

• openclaw agents list --json returns role (string or null) per agent.
• A roundtrip via openclaw agents add ... --role "Code Reviewer" followed by agents list --json shows that value.
• Gateway agents.list includes role.