# AgentTeams **Repository Path**: ATM006/AgentTeams ## Basic Information - **Project Name**: AgentTeams - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-11 - **Last Updated**: 2026-08-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

[English](./README.md) | [中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md) **AgentTeams 是一个开源的协作式多智能体运行平台。让多个 Agent 在一个受控、可审计的房间中协作，人类全程可见、随时可介入。采用 Manager-Workers 架构，Manager 统一调度多个 Workers，专注于企业内的人和 Agent、Agents 之间的协作场景。** AgentTeams 不再实现 Agent 运行时本身，而是编排和管理多个 Agent 容器（Manager 和众多 Workers）。 - 🧑‍💻 **设计了 Manger-Workers 架构**：不用真人去管理每个干活的 Worker Claw，实现由 Agent 管理 Agents。 - 🤝 **多运行时协作**：OpenClaw、QwenPaw 和 Hermes Worker 在同一个 IM 房间中共存协作。用确定性更高的 Agent（OpenClaw/QwenPaw）做 Leader 编排任务，用 Hermes Worker 执行自主编程——各司其职。 - 📚 **引入 MinIO 共享文件系统**：用于 Agent 之间的信息共享，大幅降低多 Agent 协作带来的 Token 消耗。 - ⛑️ **引入 Higress AI Gateway**：流量入口和各类凭证风险降低了，减少了用户对原生龙虾在安全上的顾虑。 - 🎨 **使用 Element IM 客户端+Tuwunel IM 服务器（均基于 Matrix 实时通信协议）**：节省钉钉、飞书 IM 的接入和企业内的审批成本，方便用户快速体验在 IM 的交互环境中体验模型服务的"爽感"，同时支持以 OpenClaw 原生的方式接入 IM。 - 🧬 **集成** [AgentLoop](https://www.aliyun.com/product/agentloop?spm=at.readme.0.0.0) ：提供 Agent 全栈观测与审计、Agent 评估与实验、Agent 资产管理与持续优化等能力。 ![架构](https://img.alicdn.com/imgextra/i4/O1CN01c1VlDE1zYZ46EW3OA_!!6000000006726-49-tps-9895-8231.webp) ## 动态 - **2026-08-08:** [Release Notes](https://github.com/agentscope-ai/AgentTeams/releases/tag/v1.2.2) — AgentTeams v1.2.2：新增 Manager 向 Worker 下发自定义 Skill，支持校验、上传存储、更新 `Worker.spec.skills`，并由 QwenPaw 无需重启即可热刷新和启用；增强 Manager 与 Worker 的 Skill 加载保护；同时确保 Team Leader 和 Worker 在受邀后显式加入 Team Room。 - **2026-08-06:** [Release Notes](https://github.com/agentscope-ai/AgentTeams/releases/tag/v1.2.1) — AgentTeams v1.2.1：将 Manager 和 Worker 运行时栈统一到 QwenPaw 2.0.1，正式发布 QwenPaw Worker 多架构镜像，增强 Matrix 与 TeamHarness 任务分配原子性以及 CoPaw 到 QwenPaw 的状态迁移，新增自定义模型视觉与推理能力覆盖，并提升 Worker 生命周期和运行时管理可靠性。 - **2026-07-30:** [Release Notes](https://github.com/agentscope-ai/AgentTeams/releases/tag/v1.2.0) — AgentTeams v1.2.0（正式版）：端到端统一 AgentTeams 命名并确立最终的 Team/Worker 资源契约；新增可选的 AgentTeams Dashboard；同时改进 Worker 存储同步、Team 路由与生命周期收敛，安装器可按旧环境变量与存储契约安装 v1.1.2（更早版本仍需使用对应的旧版安装器），并提升 Dashboard 可靠性以及工具和诊断安全性。 - **2026-07-17:** [Release Notes](https://github.com/agentscope-ai/AgentTeams/releases/tag/v1.2.0-beta.1) — AgentTeams v1.2.0-beta.1（预发布版）：完成了从已停用的前代产品的公开更名，覆盖镜像、Kubernetes API、Helm、Matrix、存储和运行时契约；新增插件平台、TeamHarness 与 WorkerFlow 集成、Matrix AppService 与 Human SSO、模型提供方路由与 LLM 预检，以及更丰富的控制器可观测性。Beta 版安装需显式手动启用（opt-in），而稳定版默认仍为 v1.1.2。 - **2026-05-27:** [Release Notes](https://github.com/agentscope-ai/AgentTeams/releases/tag/v1.1.2) — AgentTeams v1.1.2：安装器默认改为 QwenPaw 运行时并支持 keep-all 升级；Team 支持人类协调员，Team Leader 协作工具刷新；控制器支持 Nacos 远程技能与 `sts-agentteams` / `ai-registry` STS 凭据；Worker 控制器资源名与运行时名称解耦；新增控制器 reconcile 指标与优雅退出。 - **2026-05-07:** [Release Notes](https://github.com/agentscope-ai/AgentTeams/releases/tag/v1.1.1) | [Changelog](changelog/v1.1.1.md) — AgentTeams v1.1.1：Worker/Manager/Team CRD 上的声明式 MCP（破坏性变更）并扩展至 Team Leader；CR 支持自定义 `spec.env`；新增 Token Plan、Qwen 国际线路与 `qwen3.6-plus` 模型；Helm 控制器 RBAC 收敛到单命名空间；Worker 包可不含 `SOUL.md`。 - **2026-04-24:** [English](blog/agentteams-1.1.0-release.md) | [中文](blog/zh-cn/agentteams-1.1.0-release.md) — AgentTeams v1.1.0：Kubernetes 原生控制面、Hermes 自主编程 Agent 运行时、镜像体积减少 1.7 GB，`agt` CLI 替代 shell 脚本。 - **2026-04-14:** [English](blog/agentteams-k8s-native-multi-agent-collaboration.md) | [中文](blog/zh-cn/agentteams-k8s-native-multi-agent-collaboration.zh-CN.md) — 深度解析：AgentTeams 作为基于 Kubernetes 原生的多 Agent 协作编排系统。 - **2026-04-03:** [English](docs/usage/resource-management.md) | [中文](docs/zh-cn/usage/resource-management.md) — AgentTeams 1.0.9 发布：Kubernetes 风格声明式资源管理（YAML 定义 Worker、Team、Human）；上线 Worker 模板市场；支持 Manager QwenPaw 运行时；新增 Nacos Skills 注册中心等。 - **2026-03-14:** [English](blog/agentteams-1.0.6-release.md) | [中文](blog/zh-cn/agentteams-1.0.6-release.md) — AgentTeams 1.0.6：企业级 MCP Server 管理，凭证零暴露；Worker 经 Higress AI Gateway 安全调用 MCP。 - **2026-03-10:** [English](blog/agentteams-1.0.4-release.md) | [中文](blog/zh-cn/agentteams-1.0.4-release.md) — AgentTeams 1.0.4：支持 QwenPaw（原 CoPaw）Worker，内存占用降低约 80%，本地模式可操作浏览器。 - **2026-03-04:** [English](blog/agentteams-announcement.md) | [中文](blog/zh-cn/agentteams-announcement.md) — AgentTeams 以其旧名称开源，引入 Manager Agent 与多 Agent 协同平台能力。 ## 为什么选 AgentTeams - **企业级安全**：Worker 永远不持有真实的 API Key 或 GitHub PAT，只有一个消费者令牌（类似"工牌"）。即使 Worker 被攻击，攻击者也拿不到任何真实凭证。 - **多 Agent 群聊网络**：Manager Agent 智能分解任务，协调多个 Worker Agent 并行执行，大幅提升复杂任务处理能力。 - **Matrix 协议驱动**：基于开放的 Matrix IM 协议，所有 Agent 通信透明可审计，天然支持分布式部署和联邦通信。 - **人工全程监督**：人类可随时进入任意 Matrix 房间观察 Agent 对话，实时干预或修正 Agent 行为，确保安全可控。 - **真正开箱即用的 IM**：内置 Matrix 服务器，不需要申请飞书/钉钉机器人，不需要等待审批。浏览器打开 Element Web 就能对话，或者用手机上的 Matrix 客户端（Element、FluffyChat）随时指挥，iOS、Android、Web 全平台支持。 - **Manager-Worker 架构**：清晰的 Manager-Worker 两层架构，职责分明，易于扩展自定义 Worker Agent 以适应不同场景，支持纳管 Copaw、NanoClaw、ZeroClaw 或是企业自建的 Agent - **一条命令启动**：一个 `curl | bash` 搞定所有组件 — Higress AI 网关、Matrix 服务器、文件存储、Web 客户端和 Manager Agent 本身。 - **技能生态**：Worker 可以按需从 [skills.sh](https://skills.sh) 获取技能（社区已有 80,000+ 个）。因为 Worker 本身就拿不到真实凭证，所以可以放心使用公开技能库。 ## 快速开始 **前置条件**：Docker Desktop（Windows/macOS）或 Docker Engine（Linux）。若在 ECS 或云桌面等虚拟机上部署，请采用 Linux 系统，图形化需求，请使用 Ubuntu，官方镜像包暂不支持虚拟机上的 Window 系统，原因是虚拟机上的 Window 系统不是 Linux Container。 - [Docker Desktop](https://www.docker.com/products/docker-desktop/)（Windows / macOS） - [Docker Engine](https://docs.docker.com/engine/install/)（Linux）或 [Podman Desktop](https://podman-desktop.io/)（替代方案） **资源需求**：最低 2C4GB 内存。如果希望部署较多 Worker 体验更强大的 Agent Teams 能力，建议 4C8GB 内存。目前 OpenClaw 内存占用较高。Docker Desktop 用户可在 Settings → Resources 中调整。 ![资源](https://img.alicdn.com/imgextra/i4/O1CN01c8qOlx1hPiKMjzGZQ_!!6000000004270-0-tps-2496-690.jpg) 安装步骤：以下我们以最简单的本地部署、本地访问来演示安装步骤，不到5分钟就能开始玩龙虾了。第一步：打开终端，Mac 系统输入以下安装命令。 ```bash bash <(curl -sSL https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.sh) ``` **Windows（建议 PowerShell 7+）输入以下安装命令：** ```powershell Set-ExecutionPolicy Bypass -Scope Process -Force; $wc=New-Object Net.WebClient; $wc.Encoding=[Text.Encoding]::UTF8; iex $wc.DownloadString('https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.ps1') ``` 这里，输入 Mac 系统的安装命令。第二步：选择语言，选择中文。第三步：选择安装模式，快速开始请选择阿里云百炼快速安装。您也可以选择其他模型服务，手动配置。第四步：选择大模型服务商。快速开始会默认使用阿里云百炼；如果使用 DeepSeek、OpenAI、Qwen 国际站、自部署模型等服务，请选择手动配置里的 **OpenAI 兼容 API**，并填写对应的 Base URL、API Key 和模型 ID。Base URL 通常需要包含 `/v1`，例如 `https://api.deepseek.com/v1`。第五步：选择模型接口。百炼 Coding Plan 和百炼通用接口有所不同，这里我们选择 Coding Plan 接口。[购买Coding Plan](https://bailian.console.aliyun.com/cn-beijing/?source_channel=4qjGAvs1Pl&tab=coding-plan#/efm/index) 第六步：选择模型系列。如果第五步中选择的是百炼 Coding Plan，您可以选择 qwen3.5-plus、GLM等，待 Matrix room 建立起来后，还可通过发送指令，让 Manager 切换其他到模型。第七步：开始测试 API 联通性，若测试成功，效果如下。 ![测试](https://img.alicdn.com/imgextra/i4/O1CN0148wFGG1lYeWKd3Uat_!!6000000004831-2-tps-1752-600.png) 若测试不成功，您需要检查粘贴的模型 API Key 是否完整或无空格、Base URL 是否包含服务商要求的路径（常见为 `/v1`）、模型 ID 是否正确。再次尝试仍无法通过时，建议向对应模型服务厂商提交服务工单。第八步：选择网络访问模式。这里我们选择仅本机使用，若允许外部访问，例如和同事建立 Matrix roon，则选择允许外部访问。选择后，按回车键即可，确定端口号、网关主机端口、Higress 控制台主机端口、Maxtrix 域名、Element Web 直接访问的主机端口、文件系统域名等，均采用默认值，无须手动配置。第九步：GitHub 集成、Skills 注册中心、数据持久化、Docker 卷、Manager 工作空间，按回车键即可，均采用默认配置，无须手动配置。第十步：选择 Manager Worker 运行时，目前支持 OpenClaw 和 Copaw，未来还将支持 NanoClaw、ZeroClaw 等。第十一步：等待安装。安装完成。登录密码是自动生成的。若希望通过移动端来访问和使用，则需要使用美区账号下载 FluffyChat/Element Mobile。（之所以采用这两个 IM，是因为他们是支持 Matrix 协议的）下载后，连接您的 Matrix 服务器地址，就能随时随地管理您的 Agent 团队。 ![测试](https://img.alicdn.com/imgextra/i3/O1CN01Tl4T8q29HIHtPVSJL_!!6000000008042-2-tps-2372-1282.png) 第十二步：浏览器中，输入 http://127.0.0.1:18088/#/login，登录 Element，输入用户名和密码，就可以玩龙虾了，告诉 Manager 创建 Worker 并分配任务。 ![登录](https://img.alicdn.com/imgextra/i1/O1CN01C5NvV41P6msPuucrs_!!6000000001792-2-tps-2748-1224.png) ⚠️ **注意：AgentTeams 内置了 Higress AI 网关，负责模型 API Key 管理以及入口流量的安全管控。模型 API Key 的切换、新增，以及路由、域名、证书管理，均可在 Higress 控制台管理。** ![网关](https://img.alicdn.com/imgextra/i3/O1CN01dNJz4x1yJcWjHGuVj_!!6000000006558-0-tps-1596-180.jpg) ## 升级每次更新新版本，您在终端执行以下命令，即可原地升级，默认升级到最新版本： ```bash bash <(curl -sSL https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.sh) ``` 就地升级，数据和配置会保留；全新重新，会删除所有数据。若要升级到指定版本，请使用以下命令： ```bash AGENTTEAMS_VERSION=v1.2.2 bash <(curl -sSL https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.sh) ``` ## 卸载 **macOS / Linux:** ```bash bash <(curl -fsSL https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.sh) uninstall ``` **Windows (PowerShell):** ```powershell Set-ExecutionPolicy Bypass -Scope Process -Force; $wc=New-Object Net.WebClient; $wc.Encoding=[Text.Encoding]::UTF8; $s=$wc.DownloadString('https://raw.githubusercontent.com/agentscope-ai/AgentTeams/main/install/agentteams-install.ps1'); & ([scriptblock]::Create($s)) uninstall ``` 将移除所有 AgentTeams 容器（Manager、Worker、docker-proxy）、Docker 卷、网络、env 文件、工作空间目录和安装日志。 ## Kubernetes 部署（Helm）如果希望在团队内共享或生产环境部署 AgentTeams，可以使用官方 Helm Chart 在任意 Kubernetes 集群上安装。默认配置内置了 Higress AI 网关、Tuwunel（Matrix）、MinIO 与 AgentTeams Controller，无需额外依赖。以下内容用于快速安装。集群规划、values 文件、模型服务、runtime、持久化、Ingress 和运维选项参见 [Kubernetes 部署指南](docs/zh-cn/usage/deployment/kubernetes.md)。 **前置条件** - Kubernetes 1.24+（kind / minikube / k3s / 各类托管 K8s 均可） - Helm 3.7+ - 默认 StorageClass（用于 Tuwunel 与 MinIO 的 PVC） **安装（OpenAI / OpenAI 兼容模式）** ```bash helm repo add higress.io https://higress.io/helm-charts helm repo update helm install agentteams higress.io/agentteams \ -n agentteams-system --create-namespace \ --render-subchart-notes \ --set credentials.llmApiKey=<你的-API-Key> \ --set credentials.adminPassword=<你的-管理员密码> \ --set gateway.publicURL=http://localhost:18080 ``` 如果使用非 OpenAI 但兼容 OpenAI API 的服务商，还需设置 `llmBaseUrl`： ```bash helm install agentteams higress.io/agentteams \ -n agentteams-system --create-namespace \ --render-subchart-notes \ --set credentials.llmApiKey=<你的-API-Key> \ --set credentials.llmBaseUrl=https://your-provider.example.com/v1 \ --set credentials.defaultModel=your-model-name \ --set credentials.adminPassword=<你的-管理员密码> \ --set gateway.publicURL=http://localhost:18080 ```

使用通义千问（Qwen）

```bash helm install agentteams higress.io/agentteams \ -n agentteams-system --create-namespace \ --render-subchart-notes \ --set credentials.llmApiKey=<你的-通义千问-API-Key> \ --set credentials.llmProvider=qwen \ --set credentials.defaultModel=qwen3.5-plus \ --set credentials.adminPassword=<你的-管理员密码> \ --set gateway.publicURL=http://localhost:18080 ```

| 参数 | 是否必填 | 说明 | |---|---|---| | `credentials.llmApiKey` | 必填 | LLM 服务商 API Key | | `gateway.publicURL` | 必填 | 用户访问 Element Web 的对外地址（端口转发场景填 `http://localhost:18080`，正式环境填 `https://agentteams.example.com` 等） | | `credentials.adminPassword` | 推荐 | Matrix 管理员密码；留空时会自动生成（之后需要从 Secret 中读取） | | `credentials.llmProvider` | 可选 | LLM 服务商名，默认 `openai-compat` | | `credentials.defaultModel` | 可选 | 默认模型，默认 `gpt-5.4` | | `credentials.llmBaseUrl` | 可选 | OpenAI 兼容的 Base URL（例如 `https://api.deepseek.com/v1`）。使用官方 OpenAI API 时留空 | | `preflight.llm.enabled` | 可选 | 安装或升级前通过 hook 验证 LLM API Key、Base URL 和模型；默认 `true` | | `preflight.llm.strict` | 可选 | LLM 探测失败时终止安装或升级；默认 `true`，设为 `false` 时仅告警并继续 | | `preflight.llm.timeoutSeconds` | 可选 | LLM 探测单次 HTTP 请求的超时时间；默认 `30` 秒 | | `preflight.llm.retries` | 可选 | 限流、网络错误和服务商 5xx 等临时错误的重试次数；默认 `2` | | `preflight.llm.activeDeadlineSeconds` | 可选 | 探测 Job 的最长运行时间；默认 `120` 秒 | | `preflight.llm.resources` | 可选 | 探测容器的 Kubernetes requests/limits | | `manager.runtime` | 可选 | Manager Agent 运行时：OpenClaw 使用 `openclaw`（默认）；CoPaw 在当前 Chart 中使用 `qwenpaw`，`copaw` 为兼容别名。Manager 不支持 Hermes | | `worker.defaultRuntime` | 可选 | Chart 提供 `openclaw`（默认）、`copaw`、`hermes` 和 `openhuman` 的默认镜像值，但当前 CRD 不接受显式的 `spec.runtime: openhuman`；QwenPaw Worker 需在 `spec.image` 中显式配置镜像 | Helm 默认在安装和升级前执行 LLM 探测，使用 `credentials.llmApiKey`、`credentials.llmBaseUrl` 和 `credentials.defaultModel` 发送一个最小的 OpenAI 兼容请求。无效密钥、无法访问的 Base URL、不支持的模型、额度错误或服务商故障会在 Controller 启动前终止安装。受限或离线集群可以临时关闭： ```bash helm install agentteams higress.io/agentteams \ -n agentteams-system --create-namespace \ --set credentials.llmApiKey=<你的-API-Key> \ --set credentials.adminPassword=<你的-管理员密码> \ --set gateway.publicURL=http://localhost:18080 \ --set preflight.llm.enabled=false ```

使用其他运行时（CoPaw Manager + Hermes Workers）

```bash helm install agentteams higress.io/agentteams \ -n agentteams-system --create-namespace --devel \ --set manager.runtime=qwenpaw \ --set manager.image.repository=higress-registry.cn-hangzhou.cr.aliyuncs.com/agentteams/agentteams-manager-qwenpaw \ --set worker.defaultRuntime=hermes \ --set credentials.llmApiKey= \ --set credentials.llmBaseUrl=https://your-provider.example.com/v1 \ --set credentials.defaultModel=your-model-name \ --set credentials.adminPassword= \ --set gateway.publicURL=http://localhost:18080 ``` 选择 CoPaw Manager 时需要同时设置 `manager.runtime=qwenpaw` 和 `agentteams-manager-qwenpaw` 镜像。Worker 的默认镜像分别通过 `worker.defaultImage.` 配置。

**多地域镜像仓库** 默认镜像指向中国区域。如果在中国大陆以外部署，可以使用以下就近镜像仓库： | 区域 | Registry | |---|---| | 中国（默认） | `higress-registry.cn-hangzhou.cr.aliyuncs.com/higress` | | 北美 | `higress-registry.us-west-1.cr.aliyuncs.com/higress` | | 东南亚 | `higress-registry.ap-southeast-7.cr.aliyuncs.com/higress` | `global.imageRegistry` 只会影响读取该全局值的子 Chart；Controller、Manager、Worker、Tuwunel、MinIO 和 Element Web 使用各自的完整 `image.repository`。切换地域或私有仓库时，请在 values 文件中逐项覆盖相关镜像地址。完整示例和可配置项参见 [Kubernetes 部署指南](docs/zh-cn/usage/deployment/kubernetes.md)与 [`helm/agentteams/values.yaml`](helm/agentteams/values.yaml)。 **访问** 临时从本机管理集群时，可以转发 Higress Gateway： ```bash kubectl port-forward -n agentteams-system svc/higress-gateway 18080:80 ``` 然后在浏览器中打开 http://localhost:18080 登录 Element Web。命令退出后转发即停止，因此该方式不适合多人共享。公司内网或公网访问时，只需通过 HTTPS Ingress 或 LoadBalancer 暴露 `svc/higress-gateway`。`gateway.publicURL` 会写入 Element Web 配置，作为 Matrix Homeserver 地址，因此必须与用户实际打开的公网 Origin 完全一致，例如 `https://agentteams.example.com`。 1. 将公网域名解析到 Ingress Controller 或负载均衡器。 2. 在 `agentteams-system` 命名空间中准备 TLS 证书 Secret。 3. 在 Helm Release 中设置相同的公网地址： ```bash helm upgrade agentteams higress.io/agentteams \ -n agentteams-system --reuse-values \ --set gateway.publicURL=https://agentteams.example.com ``` 4. 将该域名路由到 Higress Gateway。以下通用示例假设使用 NGINX IngressClass，并已存在 `agentteams-tls` Secret；请按集群实际情况替换： ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: agentteams namespace: agentteams-system spec: ingressClassName: nginx tls: - hosts: - agentteams.example.com secretName: agentteams-tls rules: - host: agentteams.example.com http: paths: - path: / pathType: Prefix backend: service: name: higress-gateway port: number: 80 ``` DNS 与 TLS 生效后，分别验证 Web 入口和 Matrix 路由： ```bash curl -fsSI https://agentteams.example.com/ curl -fsS https://agentteams.example.com/_matrix/client/versions ``` Controller API、Tuwunel、MinIO 和 Higress Console 应保持集群内访问；如确需暴露，请另行配置身份认证和网络策略。多人共享时必须使用 HTTPS，因为 Matrix 登录凭据和 Access Token 都会经过该入口。也可以用 `LoadBalancer` Service 代替 Ingress，但 DNS、 TLS 和 `gateway.publicURL` 的要求不变。 **升级** ```bash helm repo update helm upgrade agentteams higress.io/agentteams -n agentteams-system --reuse-values ``` **卸载** ```bash helm uninstall agentteams -n agentteams-system kubectl delete namespace agentteams-system ``` 更深入的 K8s Native 架构说明（CRD、Controller、声明式 `Worker` / `Team` / `Human` 资源）请参考 [docs/zh-cn/design/k8s-native-orchestration.md](docs/zh-cn/design/k8s-native-orchestration.md)。 ## 工作方式 ### Manager 是你的 AI 管家 Manager 通过自然语言完成 Worker 的全生命周期管理： ``` 你：帮我创建一个名为 alice 的前端 Worker Manager：好的，Worker alice 已创建。房间：Worker: Alice 可以直接在房间里给 alice 分配任务了。你：@alice 帮我用 React 实现一个登录页面 Alice：收到，正在处理……[几分钟后] 完成了！PR 已提交：https://github.com/xxx/pull/1 ```

_{① Manager 创建 Worker，分配任务} _{② 人类也可以直接在房间里指挥 Worker}

Manager 还会定期发送心跳检查--如果某个 Worker 卡住了，它会自动提醒你。 ### 安全模型 ``` Worker（只持有消费者令牌） → Higress AI 网关（持有真实 API Key、GitHub PAT） → LLM API / GitHub API / MCP Server ``` Worker 只能看到自己的消费者令牌。网关统一管理所有真实凭证。Manager 知道 Worker 在做什么，但同样接触不到真实的 Key。 ### 人工全程监督每个 Matrix 房间里都有你、Manager 和相关 Worker。你可以随时跳进来： ``` 你：@bob 等一下，密码规则改成至少 8 位 Bob：好的，已修改。 Alice：前端校验也更新了。 ``` 没有黑盒，没有隐藏的 Agent 间调用。 ## AgentTeams vs OpenClaw 原生 | | OpenClaw 原生 | AgentTeams | |---|---|---| | 部署方式 | 单进程 | 分布式容器 | | Agent 创建 | 手动配置 + 重启 | 对话式 | | 凭证管理 | 每个 Agent 持有真实 Key | Worker 只持有消费者令牌 | | 人工可见性 | 可选 | 内置（Matrix 房间） | | 移动端访问 | 取决于渠道配置 | 任意 Matrix 客户端，零配置 | | 监控 | 无 | Manager 心跳，房间内可见 | ## 多运行时协作 AgentTeams 目前提供三类主要 Worker 运行时，可以**在同一个 IM 房间中共存协作**： - **OpenClaw**（Node.js）— 通用 Agent 运行时，拥有丰富的 Skills 生态，擅长任务编排和工具调用 - **QwenPaw**（Python）— 轻量级运行时，适合浏览器自动化和快速任务 - **Hermes**（[hermes-agent](https://github.com/NousResearch/hermes-agent)）— 自主编程 Agent，具备终端沙箱、自我进化的 Skill 和持久化记忆 `copaw` 仍作为已有 CoPaw Worker 的兼容 runtime 值保留；当前 CRD 同时接受 `copaw` 和 `qwenpaw`。每种运行时各有擅长。推荐模式：用确定性更高的 Agent（OpenClaw/QwenPaw）做 Leader 负责任务分解和调度，用 Hermes Worker 执行自主编程任务。所有运行时通过 Matrix 房间通信——完全可见、随时可干预。 ```bash # 原地切换任意 Worker 的运行时 agt update worker --runtime hermes ``` ## 架构 ``` ┌───────────────────────────────────────────────┐ │ agentteams-controller │ │ Higress │ Tuwunel │ MinIO │ Element Web │ └──────────────────┬────────────────────────────┘ │ Matrix + HTTP Files ┌──────────────────┴──────────┐ │ agentteams-manager-agent │ │ Manager (OpenClaw/ │ │ QwenPaw) │ └──────────────────┬──────────┘ │ ┌──────────────────┼────────────────────────────┐ │ │ │ ▼ ▼ ▼ Worker Alice Worker Bob Worker Charlie (OpenClaw) (QwenPaw) (Hermes) ``` | 组件 | 职责 | |------|------| | agentteams-controller | Kubernetes 原生控制平面，协调 Worker/Team/Manager CR | | Higress AI 网关 | LLM 代理、MCP Server 托管、凭证管理 | | Tuwunel (Matrix) | 自建 IM 服务器，承载所有 Agent + 人类通信 | | Element Web | 浏览器客户端，零配置 | | MinIO | 集中式文件存储，Worker 无状态 | ## 常见问题如果 Manager 容器启动失败，执行以下命令查看具体原因： ```bash docker exec -it agentteams-manager cat /var/log/agentteams/manager-agent.log ``` 更多常见问题（启动超时、局域网访问等）参见 [docs/zh-cn/usage/troubleshooting/faq.md](docs/zh-cn/usage/troubleshooting/faq.md)。 ### 提交 Bug 提交 Issue 前，建议先导出 Matrix 消息记录，用 AI 工具结合代码库分析问题根因，这能大幅加快修复速度。 ```bash # 导出调试日志（Matrix 消息 + Agent 会话日志，PII 自动脱敏） python scripts/export-debug-log.py --range 1h ``` 然后在 Cursor、Claude Code 等 AI 工具中打开 AgentTeams 仓库，让它分析： > "读取 debug-log/ 下的 JSONL 文件，同时分析 Matrix 消息日志和 Agent 会话日志。结合 AgentTeams 代码库，定位 [描述你的 bug] 的根因。重点关注 Agent 交互流程、工具调用失败和错误模式。" 将 AI 的分析结果贴到 [Bug Report](https://github.com/agentscope-ai/AgentTeams/issues/new?template=bug_report.yml) 中。你也可以让 AI 工具直接提交 Issue 或 PR。先安装 [GitHub CLI](https://cli.github.com/)，执行 `gh auth login` 在浏览器中完成登录，然后将 [OpenClaw GitHub skill](https://github.com/openclaw/openclaw/blob/main/skills/github/SKILL.md) 配置到你的 AI 编程工具（Cursor、Claude Code 等）中。之后直接让它根据分析结果提交 Issue 或 PR 即可。欢迎[提交 Issue](https://github.com/agentscope-ai/AgentTeams/issues)，或在 [Discord](https://discord.gg/n6mV8xEYUF) / 钉钉群里随时提问。 ## 文档浏览 [中文文档目录](docs/zh-cn/)，或从概览和快速入门开始： | | | |---|---| | [docs/zh-cn/overview.md](docs/zh-cn/overview.md) | 产品概览、核心概念与文档导航 | | [docs/zh-cn/quickstart.md](docs/zh-cn/quickstart.md) | 端到端快速入门，含验证检查点 | | [docs/zh-cn/usage/use-cases.md](docs/zh-cn/usage/use-cases.md) | 软件交付、研究、内容、故障分析和长期项目协作案例 | | [docs/zh-cn/usage/deployment/local.md](docs/zh-cn/usage/deployment/local.md) | 本地实例创建、安装选项、升级与卸载 | | [docs/zh-cn/design/architecture.md](docs/zh-cn/design/architecture.md) | 系统架构详解 | | [docs/zh-cn/usage/manager-guide.md](docs/zh-cn/usage/manager-guide.md) | Manager 配置与使用 | | [docs/zh-cn/usage/worker-guide.md](docs/zh-cn/usage/worker-guide.md) | Worker 部署与故障排查 | | [docs/zh-cn/usage/development.md](docs/zh-cn/usage/development.md) | 贡献指南与本地开发 | | [docs/zh-cn/usage/troubleshooting/faq.md](docs/zh-cn/usage/troubleshooting/faq.md) | 常见问题 | ## 构建与测试 ```bash make build # 构建所有镜像 make test # 构建 + 运行全部集成测试 make test SKIP_BUILD=1 # 不重新构建，直接运行测试 make test-quick # 快速冒烟测试（仅 test-01） ``` ## 其他命令 ```bash # 通过 CLI 向 Manager 发送任务 make replay TASK="创建一个名为 alice 的前端开发 Worker" # 卸载所有内容 make uninstall # 推送多架构镜像 make push VERSION=0.1.0 REGISTRY=ghcr.io REPO=agentscope-ai/AgentTeams make help # 查看所有可用目标 ``` ## 社区 - [Discord](https://discord.gg/NVjNA4BAVw) - [钉钉群](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OPhRSPWeie5/IMWQkyrCI34IqMdl/h/6ObYHKKzZJCI=&_dt_no_comment=1&origin=11) - 微信群--扫码加入：

微信群

## 许可证 Apache License 2.0