Agent Subagents UI#

Build and maintain the Subagents tab inside the OpenClaw Agents page.

Scope#

Use this skill for:

• adding or refining the Subagents tab under Agents
• exposing editable subagent model settings in Control UI
• wiring subagent settings into the existing config form/save path
• keeping the UI honest about what is configurable per-agent vs shared defaults
• documenting runtime precedence for subagent model selection

Core design#

Keep the feature aligned with the real runtime behavior.

Subagent model precedence is:

1. agent.subagents.model
2. agents.defaults.subagents.model
3. target agent primary model
4. runtime fallback default

Do not invent backend schema that does not exist. If the current schema only supports a single subagents.model selection and shared concurrency limits, surface that clearly in the UI.

UI pattern#

Add Subagents as an Agents-page panel beside:

• Overview
• Files
• Tools
• Skills
• Channels
• Cron

Recommended panel layout:

• Agent overrides
  • subagent model
  • subagent fallback models
  • subagent thinking level
• Shared subagent defaults
  • default subagent model
  • default fallback models
  • default thinking level
  • maxConcurrent
  • maxSpawnDepth
  • maxChildrenPerAgent
• include a short precedence note explaining which value wins

Config wiring rules#

Prefer the existing config editing path. Do not create a disconnected store.

Edit through the same config-form/save flow already used by the Agents UI:

• agents.list[i].subagents.model
• agents.list[i].subagents.thinking
• agents.defaults.subagents.model
• agents.defaults.subagents.thinking
• agents.defaults.subagents.maxConcurrent
• agents.defaults.subagents.maxSpawnDepth
• agents.defaults.subagents.maxChildrenPerAgent

If fallback models are represented as part of the existing model object shape, reuse that shape instead of inventing a new field.

Implementation checklist#

1. Add/update ui/src/ui/views/agents-panel-subagents.ts
2. Wire "subagents" through ui/src/ui/views/agents.ts
3. Add required state/type wiring in ui/src/ui/app.ts and ui/src/ui/app-view-state.ts
4. Wire change handlers in ui/src/ui/app-render.ts
5. Add/update focused UI tests
6. Build the UI and run the targeted test file

Validation#

Prefer these checks after changes:

bash

cd ~/openclaw
pnpm --dir ui exec vitest run --config vitest.config.ts src/ui/views/agents.test.ts
pnpm --dir ui build

If repo-wide typecheck is already noisy, do not claim unrelated errors belong to this feature.

References#

Read these before editing:

• references/file-map.md
• references/runtime-precedence.md

For the concrete implementation that originally shipped this feature, read:

• references/implementation-notes.txt
• references/agents-panel-subagents.ts.txt
• references/agents.ts.txt
• references/app.ts.txt
• references/app-view-state.ts.txt
• references/app-render.subagents.txt
• references/agents.test.ts.txt

Use those files as the exact reference implementation when recreating or porting the feature to another OpenClaw tree.