Teams and many Gateways
A team of agents
One Chief of Staff you talk to, and a researcher, writer and reviewer it hands work to, inside one Gateway.
Read when: One agent is not enough for a task, or you want to know what your Urbicana team does.
One command creates a small team of agents inside one Gateway: a Chief of Staff who is your single point of contact, and three specialists, a Researcher, a Writer and a Reviewer. Each has its own workspace, identity and written role. You give the Chief of Staff a task; it hands bounded pieces to the specialists, checks what comes back, and gives you one answer.
How it works
The roles
| Agent ID | Name | Does | May hand work to |
|---|---|---|---|
coordinator | Chief of Staff 🧭 | Coordinates the others and is your single point of contact. | The three specialists |
researcher | Researcher 🔎 | Find reliable evidence, compare sources, and return a cited research brief. | Nobody: returns to the coordinator |
writer | Writer ✍️ | Turn a brief and verified source material into a clear, usable draft. | Nobody |
reviewer | Reviewer 🔍 | Check artifacts against requirements and report actionable findings with evidence. | Nobody |
What the command writes
- A workspace per agent at
<workspace-root>/<id>, seeded withAGENTS.md(its operating program),SOUL.mdandIDENTITY.md. - The coordinator gets
subagents: { allowAgents: [the three specialists], delegationMode: "prefer" }; each specialist getsallowAgents: []. - The coordinator becomes the system agent if none was set.
- Existing agents stay.
The coordinator hands work out with sessions_spawn (a bounded task) or sessions_send (a follow-up), each with an objective, inputs, where to put the result, how to check it and when to stop. delegationMode is guidance to the agent, not a scheduler.
From src/agents/agent-team.ts, src/agents/agent-roles.ts, docs/reference/templates/roles/, docs/concepts/multi-agent.md:112-163.
What you need
| What | Why |
|---|---|
| The Gateway stopped, for the command | agents team create works only offline. New agent in the Control UI works while it runs. |
| Unused agent IDs | It refuses if coordinator and the others exist; use --prefix for a second team. |
Turn it on
- Control UIClick New agent. The welcome lists the roles and "5. A small team (chief of staff plus the three specialists)." Type
5and approve the proposal. - Or a terminalWith the Gateway stopped:
openclaw gateway stopopenclaw agents team create --non-interactive
It printsopenclaw gateway startCreated team with coordinator "coordinator":and each agent's workspace. - Or on a fresh install
openclaw onboard --team - ChatOpen the Chief of Staff and give it a task: "Research the options, draft a one-page brief, and have it reviewed."
Check it works
| Where | What you see |
|---|---|
openclaw agents list | coordinator, researcher, writer, reviewer. |
openclaw config get agents.entries.coordinator | allowAgents with the three specialists and delegationMode: "prefer". |
| Agent switcher → Show all | The team roster, each with its latest reply. |
| While the Chief of Staff works | Its ring reads Subagents working; the Subagents panel lists the specialists' runs. |
Limits
| Limit | Detail |
|---|---|
| Presets | One preset, team. |
| Delegation | Guidance in the prompt, not a scheduler. Specialists never hand work further. |
| Sandboxes | A sandboxed agent cannot start an unsandboxed one. |
| Personal files | Delegated tasks never get a person's USER.md. |
On Urbicana today
| Step | Today | Why | Fix and cost |
|---|---|---|---|
| Team created | Yes | The first boot runs agents team create before the Gateway starts, once per computer (agent-proxy/fly/entrypoint.sh:241-250). With main and the setup agent, a member has six agents. | None. |
| Chief of Staff is the system agent | Yes | The seed sets none, so the team command sets the coordinator. The Island opens with its chat. | None. |
| Team kept across restarts | Yes | The boot keeps the member's agents and only resets the sandbox and worker defaults. | None. |
| Hand-offs inside the sandbox | Not tried | sessions_spawn and sessions_send are allowed in the sandbox; agents_list is not, and the coordinator then uses the IDs it knows. Each agent's container mounts only its own workspace. | Run one task end to end and check with openclaw sandbox explain --agent coordinator. |
| The Island | Yes | "Who is on your team and what they are doing": Team and Workers, each worker with Running or Finished and Open transcript. | None. |
Videos to record
25 · Your team on the Island
A member's computer- Open Island. The Team section with the Chief of Staff's chat.
- Give the Chief of Staff a task.
- Workers shows "Worker: …" Running, then Finished.
- Open transcript.
26 · The Chief of Staff delegates
Any Gateway with the team- Ask: "Research X, draft a one-page brief, have it reviewed."
- The ring reads Subagents working.
- Open Subagents → Running → the Researcher's run.
- The final answer with paths, checks and open decisions.
27 · A team from New agent
Any Gateway- New agent. "5. A small team (chief of staff plus the three specialists)."
- Type
5and approve. - Agent switcher → Show all. Chief of Staff 🧭, Researcher 🔎, Writer ✍️, Reviewer 🔍.
28 · What makes a specialist
Any Gateway- Agents → Files for the Researcher:
AGENTS.md"Scope and trigger" and "Handoff contract". openclaw config get agents.entries.coordinator.allowAgentsanddelegationMode: "prefer".