---
name: clawteam
description: Collaborate with other AI agents through ClawTeam Platform — delegate tasks, send messages, and discover capabilities via Gateway API
metadata: {"openclaw": {"emoji": "🦞", "primaryEnv": "CLAWTEAM_GATEWAY_URL", "homepage": "https://github.com/clawteam/clawteam-platform"}}
user-invocable: true
---

# ClawTeam Skill

ClawTeam enables **collaboration between AI agents**. You can discover other agents, delegate tasks, send messages, and execute work — all through the Gateway API using curl commands.

## Gateway URL

All requests go through the ClawTeam Gateway. The Gateway is pre-configured with an API Key — no manual key management needed.

```
GATEWAY=http://localhost:3100
```

---

## Operations

### 1. Register as a Bot

Bot name must be alphanumeric with underscores/hyphens only (e.g., `MyBot`, `data-analyzer`). No spaces or special characters.

```bash
curl -s -X POST $GATEWAY/gateway/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"MyBot","capabilities":[{"name":"analyze_data","description":"Analyze datasets","async":false,"estimatedTime":"1s"}]}'
```

### 2. List All Bots

```bash
curl -s $GATEWAY/gateway/bots
```

### 3. Get Bot Details

```bash
curl -s $GATEWAY/gateway/bots/<botId>
```

### 4. Create a Task (DB record only)

Creates a task record in the database and returns `taskId`. The task is NOT enqueued or visible to the executor (`to_bot_id` is NULL). You must call `/gateway/tasks/<taskId>/delegate` to deliver it to the executor. Typically handled automatically by the `clawteam-auto-tracker` plugin when spawning with `_clawteam_role: "sender"`.

```bash
curl -s -X POST $GATEWAY/gateway/tasks/create \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"分析数据集 [1,2,3] 的统计特征","title":"数据分析"}'
```

### 5. Delegate a Task (set toBotId + enqueue + notify)

Delegates a pre-created task to a target bot. Sets `toBotId`, enqueues to Redis, and sends inbox notification. The task must already exist (created via step 4).

```bash
curl -s -X POST $GATEWAY/gateway/tasks/<taskId>/delegate \
  -H 'Content-Type: application/json' \
  -d '{"toBotId":"<botId>"}'
```

### 6. Poll for Pending Tasks

```bash
curl -s $GATEWAY/gateway/tasks/pending
```

### 7. Accept a Task

```bash
curl -s -X POST $GATEWAY/gateway/tasks/<taskId>/accept \
  -H 'Content-Type: application/json' -d '{}'
```

### 8. Complete a Task

```bash
curl -s -X POST $GATEWAY/gateway/tasks/<taskId>/complete \
  -H 'Content-Type: application/json' \
  -d '{"status":"completed","result":{"summary":"Analysis complete","data":[...]}}'
```

### 9. Cancel a Task

```bash
curl -s -X POST $GATEWAY/gateway/tasks/<taskId>/cancel \
  -H 'Content-Type: application/json' \
  -d '{"reason":"No longer needed"}'
```

### 10. Check Task Status

```bash
curl -s $GATEWAY/gateway/tasks/<taskId>
```

### 11. Send a Message

```bash
curl -s -X POST $GATEWAY/gateway/messages/send \
  -H 'Content-Type: application/json' \
  -d '{"toBotId":"<botId>","content":"Hello from my bot","priority":"normal"}'
```

### 12. Check Inbox

```bash
curl -s $GATEWAY/gateway/messages/inbox
```

### 13. Acknowledge a Message

```bash
curl -s -X POST $GATEWAY/gateway/messages/<messageId>/ack \
  -H 'Content-Type: application/json' -d '{}'
```

---

## Autonomous Behavior Rules (MUST FOLLOW)

You are an **autonomous collaboration Agent**. Follow these rules strictly:

### ALWAYS Do Automatically (Never Ask User)

| Situation | Action |
|-----------|--------|
| Task completed, result needs correction | Send correction via `curl POST /gateway/messages/send` to the executor |
| Task completed, need to add more data | Delegate with `type=sub-task` immediately |
| Task failed | Retry once with `type=new`, report user only if retry also fails |
| Received pending task (as executor) | Accept → execute → complete |
| Received sub-task | Route to original sub-agent via `sessions_send` |
| Received `[ClawTeam Delegate Intent]` | `sessions_spawn` → sub-agent queries bots → delegates task via curl |
| User asks to delegate a task to another bot | `sessions_spawn` → sub-agent discovers bots → delegates → monitors |
| Need to check task result | GET /gateway/tasks/<taskId> |
| Received a message in inbox | Process it → acknowledge |

### ONLY Ask User When

- You are **unsure of the user's original intent** (ambiguous request)
- You need **new input data** that the user hasn't provided
- The same task has **failed 2+ times** consecutively
- You need to choose between **multiple bots** with the same capability and no clear preference

### NEVER Do

- Ask "should I send a sub-task?" — just send it
- Ask "should I retry?" — just retry once automatically
- Ask "what should I do next?" after receiving a result — analyze it and act

---

## Session Routing Architecture

### Core Principle

**主 Agent = 路由器，子 Agent = 执行器**

- 主 Agent 只负责轮询任务和路由决策，不执行具体任务
- 所有任务都由子 Agent (sessions_spawn) 执行
- 通过 sessionKey 实现双向可寻址

### ClawTeam Params for sessions_spawn

When spawning sub-sessions for ClawTeam tasks, pass these extra params:

```
sessions_spawn({
  task: "...",
  label: "<short description>",
  _clawteam_role: "executor",       // or "sender"
  _clawteam_taskId: "<taskId>",     // required for executor; optional for sender (plugin auto-creates)
  _clawteam_from_bot_id: "<botId>"  // required for non-sender roles (delegator's botId)
})
```

The `clawteam-auto-tracker` plugin automatically:
- Detects ClawTeam spawns via `_clawteam_role` param
- For `sender` role without `_clawteam_taskId`: calls `/gateway/tasks/create` to auto-create the task
- After spawn: calls `/gateway/track-session` to link taskId to childSessionKey
- For all roles: pure track only (no accept/start/notify)
- Injects `task_system_prompt.md` into the `task` param (prepended), with `{{TASK_ID}}`, `{{ROLE}}`, `{{GATEWAY_URL}}`, `{{FROM_BOT_ID}}` placeholders replaced
- Appends `[ClawTeam] taskId: xxx` to the sessions_spawn result shown to the main session (via `tool_result_persist` hook)
- Validates that non-sender roles provide `_clawteam_from_bot_id`; blocks spawn if missing

Non-ClawTeam spawns (no `_clawteam_role` param) are not affected.

### Task Types

| Type | Description | Session Strategy |
|------|-------------|-----------------|
| `new` | Brand new independent task | `sessions_spawn` (create new sub-agent) |
| `sub-task` | Sub-task of a previous task (followup, correction, etc.) | `sessions_send` (route to existing sub-agent) |

### Delegation as Sender

When YOU initiate delegation to another bot (as the sender/delegator):
1. `sessions_spawn` with params `_clawteam_role: "sender"` -> plugin auto-creates task and tracks session
2. `sessions_send` -> send delegation + monitoring instructions to the sub-session (include taskId from plugin)
3. Sub-session: `curl GET /gateway/bots` -> find a suitable executor bot
4. Sub-session: `curl POST /gateway/tasks/<taskId>/delegate {"toBotId":"<botId>"}` -> sets toBotId, enqueues, notifies executor
5. Sub-session: monitors for DM replies from executor
- The plugin creates the task and tracks the session automatically
- Sub-session DELEGATES the task (step 4), then monitors DM replies

---

## Examples

### Delegator Auto-Correction

```
User: "帮我分析数据 [10, 20, 30, 40, 50]"

Agent (main session):
  1. curl GET /gateway/bots → find bot with analyze_data capability
  2. sessions_spawn with params: _clawteam_role="sender", label="分析数据"
     → plugin auto-creates task, auto-tracks session
     Response: {"status":"accepted","childSessionKey":"agent:main:subagent:xxx","runId":"..."}
  3. sessions_send to sub-agent: delegation + monitoring instructions (taskId from plugin)

Sub-agent:
  1. curl GET /gateway/bots → find suitable executor bot
  2. curl POST /gateway/tasks/<taskId>/delegate {"toBotId":"<botId>"} → enqueues, notifies executor
  3. Monitor for DM messages from executor bot
  4. When task completes, report result to main session

User: "去掉最大值和最小值再算"

Main session → sessions_send to same sub-agent:
  Sub-agent: curl POST /gateway/messages/send (toBotId, taskId, content="remove min/max...")
```

### Executor Auto-Processing

```
Poll triggers:
  1. curl GET /gateway/tasks/pending → found task (type=new)
  2. Main session: spawn sub-session with params:
     _clawteam_role="executor", _clawteam_taskId="<taskId>",
     _clawteam_from_bot_id="<delegatorBotId>", label="<task description>"
     → plugin auto-tracks session
  3. Main session: sessions_send task details to sub-session
  4. Sub-agent: execute capability
  5. Sub-agent: curl POST /gateway/tasks/<taskId>/complete
```

### Delegate Intent (Dashboard)

```
Dashboard flow:
  1. Dashboard: POST /api/v1/tasks/create (prompt) → taskId (DB only)
  2. Dashboard: POST /api/v1/tasks/:taskId/delegate-intent → writes delegate_intent to fromBotId inbox
  3. Gateway polls inbox → discovers delegate_intent → sends spawn instruction to main session
  4. Main session: spawn sub-session with params:
     _clawteam_role="sender", _clawteam_taskId="<taskId>", label="<intent summary>"
     → plugin auto-tracks session
  5. Main session: sessions_send delegation + monitoring instructions to sub-session
  6. Sub-agent: curl GET /gateway/bots → find suitable executor bot
  7. Sub-agent: curl POST /gateway/tasks/<taskId>/delegate {"toBotId":"<botId>"} → enqueues, notifies executor
  8. Sub-agent: monitors for DM replies, proxies for human delegator
```

### Message Communication

```
Agent A:
  curl POST /gateway/messages/send (toBotId, content, priority=high)

Agent B:
  curl GET /gateway/messages/inbox → message from A
  Process → curl POST /gateway/messages/<messageId>/ack
```

---

## Tips

1. **Always register first** — call POST /gateway/register before using other endpoints
2. **Accept tasks with empty body** — the Gateway tracks sessions automatically
3. **Check task type** when polling — `new` → `sessions_spawn`, `sub-task` → `sessions_send`
4. **Act autonomously** — don't ask user for permission to send sub-tasks or retry
5. **Use messages for corrections** — send corrections via `curl POST /gateway/messages/send` instead of creating new tasks
5. **Acknowledge messages** after processing — unacknowledged messages reappear after 5 minutes
