Summary

Control UI presents agents as a flat list. For teams coordinating via sessions_spawn + shared-workspace symlinks + TASK.json, reasoning about any single cross-agent relationship currently requires opening 5–10 files across 5 directories, because the UI surfaces each file individually but never the relationships between them.

Problem to solve

I use the stock multi-agent pattern from docs/concepts/multi-agent.md and docs/concepts/agent-workspace.md:

• A chief agent delegates to subagents via sessions_spawn, permissions declared in openclaw.json under allowAgents.
• Each agent owns a workspace at ~/.openclaw/workspace-{id}/ holding its five config files (IDENTITY.md / SOUL.md / AGENTS.md / TOOLS.md / HEARTBEAT.md).
• Agents collaborate by producing artifacts into their own workspace, then exposing them to peers via symlinks under shared-workspace/projects/{id}/ — the dataflow mechanism between agents.
• TASK.json under a project tracks step order and per-step status.

No custom runtime or glue — a team is N agents wired through allowAgents (delegate) + symlinks (dataflow) + TASK.json (sequence).

Once a team has more than 2–3 members, answering a question like "why did chief pick subagent X instead of Y?" requires:

1. Open ~/.openclaw/openclaw.json — inspect allowAgents for the chief
2. Open chief's AGENTS.md — see how subagents are described
3. Open each candidate subagent's IDENTITY.md + SOUL.md — see why one was preferred
4. Open each TOOLS.md — confirm capability overlap
5. Walk symlinks under shared-workspace/projects/{id}/ — see what was actually produced
6. Open TASK.json — check step ordering

Each file is correctly isolated for the runtime; it's the cross-reference cost between files that grows superlinearly with team size, and Control UI surfaces none of these relationships together. Configure hits the same cliff — editing one agent's five files, then walking back to check whether a sibling depends on what changed, is file-system spelunking, not a UI flow.

Proposed solution

A new Control UI tab rendering relationships already on disk + Gateway WS, with in-place editing of per-agent config. Staged as a focused PR series, each PR proposed only after the previous one lands:

1. Graph rendering — three edge types sourced from existing files (delegate from openclaw.json allowAgents, dataflow from shared-workspace/projects/ symlinks, sequence from TASK.json step order) + per-session status badges from the Gateway WS.
2. In-place config editing — click an agent → side panel edits its five markdown files; fs.watch picks up the write.
3. tools.allow editing — per-agent write access to tools.allow in openclaw.json; inherited entries from team/global rendered read-only.
4. Skills toggling — per-agent override of agents.list[].skills, respecting the absent-key / empty-array / explicit-list trinary (inherit defaults / explicitly disable all / explicit override).
5. Agent chat — in-tab chat pane over the existing Gateway WS; one session per agent, history keyed by sessionKey.

Each slice writes to files OpenClaw already owns (or uses the Gateway protocol as-is). No new storage, runtime state, or protocol changes.

Alternatives considered

• Keep the prototype external (status quo for me). Solves my problem, doesn't solve the onboarding cliff for anyone who doesn't run a custom tool.
• Fold into the existing agents tab. Rejected — agents is list-shaped, and the core problem is the relationships between agents, which a list can't express. A separate tab preserves list ergonomics for the single-agent case.
• CLI-only tooling (e.g. openclaw team graph --format dot). Useful for scripting, but doesn't address the live debugging loop where "click an edge to see the underlying record" is the actual need.
• Graph rendering library choice — hand-rolled SVG + Lit (zero new deps, fits existing Lit style), a framework-agnostic lib (cytoscape / @antv/g6 / elkjs), or an isolated React island. Tentative lean: hand-rolled SVG for v1 (≤100 nodes is well in range), but open to direction.

Impact

• Who's affected: anyone graduating from a single agent to a team — named as a UX priority in CONTRIBUTING.md's "Current Focus" ("Improving the onboarding wizard and error messages").
• Severity: moderate-high. Not a correctness bug — the runtime is fine. But a predictable drop-off where users stop scaling their setup because inspection cost crosses a threshold.
• Frequency: every time someone debugs a cross-agent delegate, dataflow, or sequencing decision. On a 5-agent team: multiple times per working session.
• Current workaround cost: O(N²) file opens per question, because a delegate decision potentially pulls in every other agent's five files.

Evidence/examples

Concrete file-count for a 5-agent team (chief + 4 subagents, one active project):

• 1× openclaw.json — delegate graph + defaults
• 5× AGENTS.md — how each describes peers
• 5× IDENTITY.md + 5× SOUL.md — role/personality
• 5× TOOLS.md — capability
• N× symlinks under shared-workspace/projects/{id}/ — per-project dataflow
• 1× TASK.json — step order

= 22+ files to hold in mind for a single "why is this team misbehaving?" question.

I've prototyped the proposed solution locally over the past few months and have a short demo I can share if it would help the discussion.

Additional information

Explicitly NOT in this proposal:

• No new runtime, storage, or protocol.
• Not a replacement for agents / sessions / channels / skills / logs tabs — a separate tab alongside them.
• No graph-shape mutations (create agent / team / symlink) in any of the five slices above. Those can be considered separately later if they're worth doing.

Happy to reshape based on feedback, including splitting or dropping slices. If "not planned", that's equally useful to hear — I'll continue with my local workflow and stop looking for the right format.

Environment: OpenClaw CLI latest, Control UI latest, macOS. Prototype tested against local ~/.openclaw/ only.