Tools
Agent Team
By Multi-agent team coordination plugin for OpenClaw
Install
npm install
pnpmConfiguration Example
{
"plugins": [
{
"id": "openclaw-agent-team",
"config": {
"maxTeammatesPerTeam": 10,
"defaultAgentType": "general-purpose",
"teamsDir": "~/.openclaw/teams"
}
}
],
"tools": {
"sessions": {
"visibility": "all"
},
"agentToAgent": {
"enabled": true,
"allow": [
"*"
]
}
}
}README
# OpenClaw Agent Team
> Multi-agent team coordination plugin for OpenClaw with shared task ledger and inter-agent messaging.
[](https://www.typescriptlang.org/)
[](https://nodejs.org)
[](https://openclaw.dev)
[](LICENSE)
[](https://twitter.com/FradSer)
[English](README.md) | [็ฎไฝไธญๆ](README.zh-CN.md)
## Overview
`@fradser/openclaw-agent-team` is an OpenClaw plugin that enables sophisticated multi-agent coordination through:
- **Team Management** โ Create and manage teams of AI agents working together
- **Member Tracking** โ JSONL-based teammate member persistence
- **Inter-Agent Messaging** โ Direct communication between teammates via the `agent-team` channel
- **Dynamic Spawning** โ Spawn new agent teammates on-demand with custom configurations
- **Workspace Isolation** โ Each teammate gets dedicated workspace and agent directories
## Features
- **3 Agent Tools**: `team_create`, `team_shutdown`, `teammate_spawn`
- **JSONL Persistence**: Lightweight, append-only storage for member data
- **Channel Plugin**: Built-in `agent-team` messaging channel for teammate communication
- **Context Injection**: Automatic teammate context via `before_prompt_build` hook
- **Capacity Management**: Configurable team size limits (1-50 teammates)
- **Path Traversal Protection**: Secure file operations with validation
- **TypeBox Validation**: Runtime schema validation for all data structures
## Installation
### Prerequisites
- Node.js >= 20.0.0
- OpenClaw >= 2026.3.2
- pnpm (recommended)
### Install from npm
```bash
openclaw plugins install @fradser/openclaw-agent-team
```
### Install from source
```bash
git clone https://github.com/FradSer/openclaw-agent-team.git
cd openclaw-agent-team
pnpm install
pnpm build
```
### Configure OpenClaw
Add to your OpenClaw configuration:
```json
{
"plugins": [
{
"id": "openclaw-agent-team",
"config": {
"maxTeammatesPerTeam": 10,
"defaultAgentType": "general-purpose",
"teamsDir": "~/.openclaw/teams"
}
}
],
"tools": {
"sessions": {
"visibility": "all"
},
"agentToAgent": {
"enabled": true,
"allow": [
"*"
]
}
}
}
```
> **Important**: The `tools.agentToAgent.enabled` configuration must be set to `true` to allow inter-agent messaging, and `tools.sessions.visibility` must be `"all"` for teammates to see each other.
## Usage Guide
You don't need to manually invoke the JSON tool calls. Once the plugin is installed and configured, you can simply ask the primary agent in plain language to start a team.
The primary agent will act as the "Team Leader", dynamically creating the team, spawning teammates, assigning tasks, and chatting with them.
**Example Prompts:**
- `"Create an agent team to research the latest AI models and write a report. I need one researcher and one writer."`
- `"Spawn a team to help me refactor this project. One agent should read the code and propose changes, another should write the tests."`
- `"Let's build a small web app. Create a frontend developer agent and a backend developer agent to work on it together in a team."`
## Quick Start (Under the Hood)
### 1. Create a Team
```typescript
// Agent uses the team_create tool
{
"tool": "team_create",
"input": {
"team_name": "research-team",
"description": "Team for research and analysis tasks",
"agent_type": "researcher"
}
}
```
### 2. Spawn Teammates
```typescript
// Spawn a teammate
{
"tool": "teammate_spawn",
"input": {
"team_name": "research-team",
"name": "analyst-1",
"agent_type": "data-analyst",
"model": "claude-opus-4-6"
}
}
```
### 3. Send Messages
```typescript
// Use the agent-team channel
{
"channel": "agent-team",
"target": "research-team:analyst-1",
"message": "Please analyze the latest dataset"
}
```
### 4. Shutdown Team
```typescript
// Gracefully shutdown and cleanup
{
"tool": "team_shutdown",
"input": {
"team_name": "research-team",
"reason": "Project completed"
}
}
```
## How It Works
The `@fradser/openclaw-agent-team` plugin deeply integrates with OpenClaw's runtime to enable multi-agent coordination:
1. **Team Creation (`team_create`)**: When an agent uses the `team_create` tool, the plugin creates a dedicated team directory under `~/.openclaw/teams/` and initializes a `config.json` and a JSONL-based member ledger.
2. **Dynamic Teammate Spawning (`teammate_spawn`)**: When the `teammate_spawn` tool is called, the plugin validates the request and creates a new OpenClaw session (sub-agent). Crucially, it **binds** this new agent to the OpenClaw runtime (`runtime.agents.set(...)`), dynamically injecting its session key, tools, and configurations so the new teammate runs immediately within the same OpenClaw daemon.
3. **Context Injection**: Through the `before_prompt_build` hook, the plugin automatically injects team awareness into every teammate's prompt. This allows agents to intuitively know their role, the current active team members, and how to communicate with others.
4. **Inter-Agent Messaging**: The built-in `agent-team` channel plugin allows agents to address each other using the format `teamName:teammateName`. Messages are appended to individual `messages.jsonl` files in the team's inbox, and OpenClaw routes them securely to the target agent session.
## Architecture
The plugin follows a 4-layer architecture with strict inward dependencies:
```mermaid
graph TB
subgraph Tools["Tools Layer"]
TeamCreate[team-create.ts]
TeamShutdown[team-shutdown.ts]
TeammateSpawn[teammate-spawn.ts]
end
subgraph Core["Core Layer"]
Index[index.ts]
Ledger[ledger.ts]
Channel[channel.ts]
Runtime[runtime.ts]
ContextInjection[context-injection.ts]
DynamicTeammate[dynamic-teammate.ts]
end
subgraph StorageLayer["Storage Layer"]
Storage[storage.ts]
end
subgraph Foundation["Foundation Layer"]
Types[types.ts]
end
Tools --> Core
Core --> StorageLayer
StorageLayer --> Foundation
```
### Layer Responsibilities
- **Foundation**: TypeBox schemas, validation, constants
- **Storage**: File system operations, directory management, config I/O
- **Core**: Business logic, ledger operations, messaging, runtime management
- **Tools**: Agent-facing tool implementations
## API Reference
### team_create
Create a new team with a unique name.
**Input Schema:**
```typescript
{
team_name: string; // 1-50 chars, lowercase alphanumeric and hyphens
description?: string; // Optional team description
agent_type?: string; // Optional default agent type
}
```
**Returns:**
```typescript
{
teamId: string; // Generated UUID
teamName: string; // Normalized team name
status: "active"; // Team status
}
```
**Error Codes:**
- `DUPLICATE_TEAM_NAME` โ Team already exists
- `INVALID_TEAM_NAME` โ Name fails validation
- `TEAM_NAME_TOO_LONG` โ Name exceeds 50 characters
- `EMPTY_TEAM_NAME` โ Name is empty
### teammate_spawn
Spawn a new agent teammate in an existing team.
**Input Schema:**
```typescript
{
team_name: string; // Existing team name
name: string; // Teammate name (auto-sanitized)
agent_type?: string; // Optional agent type override
model?: string; // Optional model override
tools?: { // Optional tool restrictions
allow?: string[]; // Whitelist of allowed tools
deny?: string[]; // Blacklist of denied tools
};
}
```
**Returns:**
```typescript
{
agentId: string; // Format: "teammate:{teamName}:{name}"
sessionKey: string; // Format: "agent:{agentId}:main"
status: "idle"; // Initial status
}
```
**Error Codes:**
- `TEAM_NOT_FOUND` โ Team doesn't exist
- `TEAM_NOT_ACTIVE` โ Team is shutdown
- `TEAM_AT_CAPACITY` โ Max teammates reached
- `DUPLICATE_TEAMMATE_NAME` โ Name already in use
- `INVALID_TEAMMATE_NAME` โ Name fails validation
### team_shutdown
Gracefully shutdown a team and delete all data.
**Input Schema:**
```typescript
{
team_name: string; // Team to shutdown
reason?: string; // Optional shutdown reason
}
```
**Returns:**
```typescript
{
teamName: string; // Shutdown team name
status: "shutdown"; // Final status
teammatesShutdown: number; // Count of teammates shutdown
}
```
**Error Codes:**
- `TEAM_NOT_FOUND` โ Team doesn't exist
- `TEAM_ALREADY_SHUTDOWN` โ Team already shutdown
## Configuration
Configure the plugin via OpenClaw's plugin configuration:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `maxTeammatesPerTeam` | number | 10 | Maximum teammates per team (1-50) |
| `defaultAgentType` | string | "general-purpose" | Default agent type for teammates |
| `teamsDir` | string | "~/.openclaw/teams" | Directory for team data storage |
**Example:**
```json
{
"plugins": [
{
"id": "openclaw-agent-team",
"config": {
"maxTeammatesPerTeam": 20,
"defaultAgentType": "specialist",
"teamsDir": "/custom/path/teams"
}
}
]
}
```
## Data Storage
Teams are stored in `~/.openclaw/teams/{team-name}/` (or custom `teamsDir`):
```
{team-name}/
โโโ config.json # TeamConfig JSON
โโโ members.jsonl # Teammate member records
โโโ agents/
โ โโโ {teammateName}/ # Teammate workspace directory
โ โโโ workspace/ # Agent working directory
โ โโโ agent/ # Agent directory
โโโ inbox/
... (truncated)
tools
Comments
Sign in to leave a comment