TeamClaw — AI Team Orchestration
Orchestrate a virtual software team through natural conversation. Submit requirements, monitor progress, review deliverables, and answer clarifications — all without leaving your chat.
When to Use This Skill
Activate when the user:
- - Wants to build, create, or implement something (e.g., "build me a todo app", "create an auth system")
- Asks to delegate work to a team (e.g., "have the team work on this", "assign this to the developer")
- Wants to check team status (e.g., "what are the workers doing?", "show me task progress")
- Needs to review results (e.g., "show me what the developer built", "check the QA report")
- Has pending clarifications to answer (e.g., "are there questions from the team?")
- Mentions teamclaw by name
Prerequisites
TeamClaw must be running in controller mode. Detect the controller URL:
CODEBLOCK0
If the health check fails, tell the user to start TeamClaw first (install the teamclaw-setup skill for guidance).
Core Workflow
1. Submit a Requirement
When the user describes what they want built, submit it to the controller intake:
CODEBLOCK1
The controller will:
- 1. Analyze the requirement
- Decompose it into tasks for appropriate roles (developer, architect, QA, etc.)
- Assign tasks to available workers
- Return a controller run with tracking info
Response fields:
- -
controllerRun.id — run identifier for tracking - INLINECODE2 —
running, completed, INLINECODE5 - INLINECODE6 — the controller agent's orchestration output
Important: The intake call may take 30-180 seconds as the controller agent plans and decomposes the work. Use --max-time 300 with curl for large requirements.
2. Monitor Progress
Check team overview
CODEBLOCK2
Key response fields:
- -
workers — map of all workers with their status (idle, busy, offline) - INLINECODE12 — map of all tasks with status (
pending, assigned, in-progress, completed, failed) - INLINECODE18 — number of unanswered questions from workers
- INLINECODE19 — orchestration run history
List tasks
CODEBLOCK3
Get task details with execution history
CODEBLOCK4
Returns the task with full execution log (lifecycle events, progress updates, errors).
List workers
CODEBLOCK5
3. Review Results
When a task completes, its result contract contains structured deliverables:
CODEBLOCK6
The resultContract includes:
- -
summary — what was accomplished - INLINECODE22 — list of files, notes, or artifacts produced
- INLINECODE23 — patterns noticed during execution
- INLINECODE24 — recommended follow-up actions
4. Handle Clarifications
Workers may need clarification to proceed. Check and answer them:
CODEBLOCK7
5. Create Individual Tasks
For fine-grained control, create tasks directly:
CODEBLOCK8
Valid roles: pm, architect, developer, qa, release-engineer, infra-engineer, devops, security-engineer, designer, marketing.
Valid priorities: low, medium, high.
6. Send Messages to the Team
CODEBLOCK9
Response Presentation
When presenting results to the user:
- 1. After intake submission: Summarize what the controller planned — how many tasks, which roles assigned, estimated workflow.
- 2. For status checks: Show a concise table of workers and tasks:
CODEBLOCK10
- 3. For completed tasks: Highlight the deliverables, key files changed, and suggested next steps.
- 4. For clarifications: Present the question clearly and ask the user to provide an answer.
Web UI
TeamClaw also provides a web dashboard for visual monitoring:
CODEBLOCK11
Mention this to users who prefer a visual overview.
Troubleshooting
| Issue | Solution |
|---|
| Health check fails | Ensure TeamClaw plugin is enabled in controller mode: INLINECODE38 |
| No workers available |
Check processModel config; single-process creates workers automatically |
| Intake times out | Increase
taskTimeoutMs in TeamClaw config; ensure AI model is responsive |
| Task stuck in pending | No idle worker for the assigned role; check
GET /api/v1/workers |
| Clarification blocking | Answer pending clarifications via
POST /api/v1/clarifications/:id/answer |
Read references for detailed API docs
Read references/api-quick-ref.md for the complete endpoint reference when you need exact request/response formats.
TeamClaw — AI团队编排
通过自然对话编排虚拟软件团队。提交需求、监控进度、审查交付物并回答澄清问题——全程无需离开聊天界面。
何时使用此技能
当用户出现以下情况时激活：
- - 想要构建、创建或实现某些内容（例如帮我建一个待办事项应用、创建一个认证系统）
- 要求将工作委派给团队（例如让团队处理这个、把这个分配给开发人员）
- 想要查看团队状态（例如工作人员在做什么？、显示任务进度）
- 需要审查结果（例如展示开发人员构建的内容、检查QA报告）
- 有待处理的澄清问题需要回答（例如团队有疑问吗？）
- 明确提到teamclaw名称
前置条件
TeamClaw必须以控制器模式运行。检测控制器URL：
bash
默认控制器URL
TEAMCLAW_URL=http://127.0.0.1:9527
健康检查 — 验证控制器是否在运行
curl -sf $TEAMCLAW_URL/api/v1/health
如果健康检查失败，请告知用户先启动TeamClaw（安装teamclaw-setup技能获取指导）。
核心工作流程
1. 提交需求
当用户描述他们想要构建的内容时，将其提交到控制器接收接口：
bash
curl -s -X POST $TEAMCLAW_URL/api/v1/controller/intake \
-H Content-Type: application/json \
-d {message: <用户需求>}
控制器将：
- 1. 分析需求
- 将其分解为适合不同角色（开发人员、架构师、QA等）的任务
- 将任务分配给可用的工作人员
- 返回带有跟踪信息的控制器运行记录
响应字段：
- - controllerRun.id — 用于跟踪的运行标识符
- controllerRun.status — running（运行中）、completed（已完成）、failed（失败）
- result — 控制器代理的编排输出
重要提示： 由于控制器代理需要规划和分解工作，接收调用可能需要30-180秒。对于大型需求，请使用--max-time 300参数。
2. 监控进度
查看团队概览
bash
curl -s $TEAMCLAW_URL/api/v1/team/status
关键响应字段：
- - workers — 所有工作人员及其状态映射（idle空闲、busy忙碌、offline离线）
- tasks — 所有任务及其状态映射（pending待处理、assigned已分配、in-progress进行中、completed已完成、failed失败）
- pendingClarificationCount — 工作人员未回答的问题数量
- controllerRuns — 编排运行历史
列出任务
bash
curl -s $TEAMCLAW_URL/api/v1/tasks
获取任务详情及执行历史
bash
curl -s $TEAMCLAW_URL/api/v1/tasks/
/execution
返回包含完整执行日志的任务（生命周期事件、进度更新、错误信息）。
列出工作人员
bash
curl -s $TEAMCLAW_URL/api/v1/workers
3. 审查结果
任务完成后，其结果合约包含结构化的交付物：
bash
获取任务以查看其结果合约
curl -s $TEAMCLAW_URL/api/v1/tasks/
resultContract包含：
- - summary — 完成的工作摘要
- deliverables[] — 生成的文件、笔记或工件列表
- discoveredPatterns[] — 执行过程中发现的模式
- suggestedNextSteps[] — 建议的后续操作
4. 处理澄清问题
工作人员可能需要澄清才能继续工作。检查并回答它们：
bash
列出待处理的澄清问题
curl -s $TEAMCLAW_URL/api/v1/clarifications
回答澄清问题
curl -s -X POST $TEAMCLAW_URL/api/v1/clarifications//answer \
-H Content-Type: application/json \
-d {answer: <你的回答>, answeredBy: user}
5. 创建独立任务
如需精细控制，可直接创建任务：
bash
curl -s -X POST $TEAMCLAW_URL/api/v1/tasks \
-H Content-Type: application/json \
-d {
title: 实现用户登录,
description: 创建包含邮箱/密码认证的登录表单,
priority: high,
assignedRole: developer
}
有效角色：pm（项目经理）、architect（架构师）、developer（开发人员）、qa（质量保证）、release-engineer（发布工程师）、infra-engineer（基础设施工程师）、devops（开发运维）、security-engineer（安全工程师）、designer（设计师）、marketing（市场营销）。
有效优先级：low（低）、medium（中）、high（高）。
6. 向团队发送消息
bash
向特定角色发送直接消息
curl -s -X POST $TEAMCLAW_URL/api/v1/messages/direct \
-H Content-Type: application/json \
-d {
from: user,
toRole: developer,
content: 请同时添加输入验证
}
向所有工作人员广播消息
curl -s -X POST $TEAMCLAW_URL/api/v1/messages/broadcast \
-H Content-Type: application/json \
-d {
from: user,
content: 截止日期提前了——优先处理核心功能
}
响应展示
向用户展示结果时：
- 1. 提交接收后：总结控制器的规划内容——任务数量、分配的角色、预估工作流程。
- 2. 状态检查时：以简洁表格展示工作人员和任务：
工作人员：3名活跃（开发人员：忙碌，QA：空闲，架构师：空闲）
任务：共5个（2个已完成，1个进行中，2个待处理）
待澄清问题：1个
- 3. 任务完成时：突出显示交付物、关键文件变更和建议的后续步骤。
- 4. 处理澄清问题时：清晰呈现问题并请用户提供答案。
Web界面
TeamClaw还提供用于可视化监控的Web仪表板：
在浏览器中打开：$TEAMCLAW_URL/ui
向偏好可视化概览的用户提及此功能。
故障排除
| 问题 | 解决方案 |
|---|
| 健康检查失败 | 确保TeamClaw插件以控制器模式启用：openclaw plugins list |
| 没有可用工作人员 |
检查processModel配置；单进程会自动创建工作人员 |
| 接收超时 | 增加TeamClaw配置中的taskTimeoutMs；确保AI模型响应正常 |
| 任务卡在待处理状态 | 没有空闲工作人员匹配分配的角色；检查GET /api/v1/workers |
| 澄清问题阻塞 | 通过POST /api/v1/clarifications/:id/answer回答待处理的澄清问题 |
阅读参考文档获取详细API文档
当需要精确的请求/响应格式时，请阅读references/api-quick-ref.md获取完整端点参考。
