Channels
Agent Teams
By Declarative multi-agent team coordination plugin for OpenClaw
Install
npm install
npmConfiguration Example
{
"teams": {
"my-team": {
"description": "My first team",
"coordination": "peer",
"members": {
"alice": {
"role": "General-purpose assistant that helps with coding tasks"
}
}
}
}
}README
# openclaw-plugin-agent-teams
Declarative multi-agent team coordination for OpenClaw.
## Overview
Agent Teams lets you define multi-agent teams in JSON. Teams coordinate through shared tools, messaging, and memory — no custom orchestration code needed.
**Features:**
- Two coordination modes: **Orchestrator** (leader assigns & approves) and **Peer** (skill-based routing)
- 5 built-in tools for runs, tasks, memory, messaging, and inbox
- Shared state: KV store, event queue, document pool, message store, activity log
- File-based event broadcasting (`.jsonl`)
- Workflow templates with stages, fail-loopback, and approval gates
- Learning system with auto-capture and cross-run persistence
- CLI agent support — spawn external Claude, Codex, or Gemini agents via PTY
- `/team` slash commands for status, control, and debugging
## Architecture
```
┌─────────────────────────┐
│ openclaw.plugin.json │
│ (team config) │
└──────────┬──────────────┘
│
┌────────────────┼────────────────┐
│ │ │
┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ Tools │ │ Hooks │ │ Commands │
│ 5 tools │ │ 5 hooks │ │ /team ... │
└────┬────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
┌────▼───────────────▼────────────────▼────┐
│ State Stores │
│ KV · Events · Docs · Runs · Messages │
│ Activity Log │
├──────────────────────────────────────────┤
│ CLI Agents (PTY) │ Broadcast (.jsonl) │
└──────────────────────────────────────────┘
```
Config is validated and parsed at activation. Stores are initialized per team with file-backed persistence (atomic write via tmp + rename). CLI agent infrastructure (IPC server + PTY spawner) starts only when CLI members are configured.
## Prerequisites
- **OpenClaw** >= 2026.2.26
- **Node.js** >= 22
- **node-pty** (optional) — required only if using CLI agents (`cli: "claude"` etc.)
## Installation
### Quick Start
```bash
# Clone into the conventional plugins directory
mkdir -p ~/.openclaw/workspace/plugins
cd ~/.openclaw/workspace/plugins
git clone https://github.com/kuan0808/openclaw-agent-teams-plugin.git agent-teams
cd agent-teams
npm install
npm run build
# Register & enable
openclaw plugins install .
```
This plugin requires team configuration to function. After installing, use the built-in [onboarding skill](#onboarding-skill) to set up your first team interactively:
```
You: "set up agent teams"
```
Or configure manually — see [Configuration](#configuration) for examples.
### Manual Registration
If you prefer manual control or need to keep existing plugins in your config, clone and build as above, then register manually instead of using `openclaw plugins install`:
```bash
# Add to allowed plugins list (keep any existing plugins in the array)
openclaw config set plugins.allow '["agent-teams"]'
# Tell OpenClaw where to find the plugin
openclaw config set plugins.load.paths '["~/.openclaw/workspace/plugins/agent-teams"]'
# Enable the plugin
openclaw config set plugins.entries.agent-teams.enabled true
```
### Dev Mode
```bash
npm run build
openclaw plugins link .
```
Use `npm run dev` for watch mode during development.
## Configuration
### Minimal Peer Team
```json
{
"teams": {
"my-team": {
"description": "My first team",
"coordination": "peer",
"members": {
"alice": {
"role": "General-purpose assistant that helps with coding tasks"
}
}
}
}
}
```
### Orchestrator Team
```json
{
"teams": {
"product": {
"description": "Product development team",
"coordination": "orchestrator",
"orchestrator": "pm",
"members": {
"pm": {
"role": "Project manager. Breaks down goals into tasks, assigns work, reviews results.",
"can_delegate": true
},
"frontend": {
"role": "Frontend developer specializing in React and UI/UX",
"skills": ["frontend", "react", "css", "ui"]
},
"backend": {
"role": "Backend developer specializing in APIs and databases",
"skills": ["backend", "api", "database", "nodejs"]
}
}
}
}
}
```
### Team Config Reference
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `description` | string | Yes | What this team does |
| `coordination` | `"orchestrator"` \| `"peer"` | Yes | Coordination mode |
| `orchestrator` | string | Orchestrator only | Member key of the team leader |
| `members` | object | Yes | Member definitions (at least one) |
| `shared_memory` | object | No | Memory store configuration |
| `routing` | object | No | Task routing settings |
| `workflow` | object | No | Workflow and gate settings |
| `knowledge` | object | No | Learning system settings |
### Member Config Reference
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `role` | string | — | Role description (required unless `role_file` set) |
| `role_file` | string | — | Path to file containing role description |
| `model` | `{ primary: string }` | — | Model override |
| `skills` | string[] | — | Skill tags for routing (e.g., `["frontend", "react"]`) |
| `can_delegate` | boolean | `false` | Whether this member can create tasks for others |
| `tools` | `{ deny?, allow? }` | — | Tool access restrictions |
| `cli` | `"claude"` \| `"codex"` \| `"gemini"` | — | Spawn as external CLI agent |
| `cli_options` | object | — | CLI-specific settings (see [CLI Agents](#cli-agents)) |
### Defaults
| Field | Default |
|-------|---------|
| `workflow.max_rounds` | `10` |
| `workflow.timeout` | `600` (seconds) |
| `knowledge.retention` | `"across-runs"` |
| `knowledge.consolidation` | `true` |
| `knowledge.consolidation_timeout` | `30` (seconds) |
| `knowledge.notify_leader` | `true` |
| `routing.fallback` | `"orchestrator"` |
| `shared_memory.enabled` | `true` |
## Tools
| Tool | Purpose | Key Params |
|------|---------|------------|
| `team_run` | Manage execution runs | `action`: start / status / complete / cancel |
| `team_task` | Create, update, query tasks | `action`: create / update / query; `deliverables`, `learning` |
| `team_memory` | Read/write shared memory | `store`: kv / docs; `action`: get / set / delete / list |
| `team_send` | Send messages & publish events | `to` (direct), `topic` (pub/sub) |
| `team_inbox` | Read messages, events, activity | `source`: inbox / events / activity |
### Typical Workflow
```
1. team_run(action: "start", goal: "Build feature X")
→ Creates a run, returns run_id
→ If workflow template exists, auto-generates task chain
2. team_task(action: "create", description: "Implement API endpoint")
→ Routes to best member via skill matching
→ Returns task_id, assigned_to
3. team_task(action: "update", task_id: "...", status: "COMPLETED",
result: "API endpoint implemented", deliverables: [...])
→ Marks task done, captures learnings, unblocks dependents
4. team_send(to: "pm", message: "API is ready for review")
→ Direct message to a specific member
5. team_run(action: "complete", result: "Feature X shipped")
→ Closes the run, collects all learnings
```
## Commands
All commands use the `/team` prefix:
| Command | Description | Auth Required |
|---------|-------------|---------------|
| `/team status [name]` | Show run progress, task board, active members | No |
| `/team list` | List all teams with member count and status | No |
| `/team stop <name>` | Cancel the current run for a team | Yes |
| `/team agents` | Show status of all CLI agents | No |
| `/team logs <team/member>` | Print CLI agent log file path | No |
| `/team start <team/member>` | Manually spawn a CLI agent | Yes |
| `/team stop-agent <team/member>` | Kill a running CLI agent | Yes |
Commands accepting `<team/member>` also accept just `<member>` if the member name is unique across teams.
## Key Concepts
### Coordination Modes
- **Orchestrator** — One leader member assigns tasks, reviews results, and has approval authority. Best for structured workflows with clear task ownership. Requires the `orchestrator` field to name the leader.
- **Peer** — All members are equal. Tasks route automatically via skill matching. Best for collaborative work where any member can pick up tasks.
### Agent IDs
All team agents use the format `at--<team>--<member>`. For example, team `product` member `frontend` → agent ID `at--product--frontend`. The `team` parameter is auto-resolved for team agents.
### Task State Machine
```
BLOCKED → PENDING → WORKING → COMPLETED
↘ ↗
INPUT_REQUIRED
↘
FAILED / CANCELED
```
- **BLOCKED** — Waiting for `depends_on` tasks to complete
- **PENDING** — Ready to be picked up
- **WORKING** — Currently being worked on
- **INPUT_REQUIRED** — Needs clarification or human input
- **COMPLETED** — Done (may trigger auto-learning capture)
- **FAILED** — Failed (triggers fail-loopback if workflow template configured)
- **CANCELED** — Canceled (e.g., by run cancellation)
### Three-Layer Routing
1. **Direct** — `assign_to: "member-name"` bypasses all routing
2. **Skill match** — `required_skills` matched against member `skills[]` with load balancing
3. **Fallback** — Uses `routing.fallback` (default: `"orchestrator"`)
### Learning System
Learnings are auto-captured on task completion or failure:
- **Explicit** — Provide `lear
... (truncated)
channels
Comments
Sign in to leave a comment