AgentTeams/README.zh-CN.md at main · agentscope-ai/AgentTeams

English | 中文 | 日本語

AgentTeams（原 HiClaw）是一个开源的协作式多智能体运行平台。让多个 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。

动态

2026-05-27: Release Notes — AgentTeams v1.1.2：安装器默认改为 QwenPaw 运行时并支持 keep-all 升级；Team 支持人类协调员，Team Leader 协作工具刷新；控制器支持 Nacos 远程技能与 sts-hiclaw / ai-registry STS 凭据；Worker 控制器资源名与运行时名称解耦；新增控制器 reconcile 指标与优雅退出。
2026-05-07: Release Notes | Changelog — 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 | 中文 — AgentTeams v1.1.0：Kubernetes 原生控制面、Hermes 自主编程 Agent 运行时、镜像体积减少 1.7 GB，hiclaw CLI 替代 shell 脚本。
2026-04-14: English | 中文 — 深度解析：AgentTeams 作为基于 Kubernetes 原生的多 Agent 协作编排系统。
2026-04-03: English | 中文 — AgentTeams 1.0.9 发布：Kubernetes 风格声明式资源管理（YAML 定义 Worker、Team、Human）；上线 Worker 模板市场；支持 Manager QwenPaw 运行时；新增 Nacos Skills 注册中心等。
2026-03-14: English | 中文 — AgentTeams 1.0.6：企业级 MCP Server 管理，凭证零暴露；Worker 经 Higress AI Gateway 安全调用 MCP。
2026-03-10: English | 中文 — AgentTeams 1.0.4：支持 QwenPaw（原 CoPaw）Worker，内存占用降低约 80%，本地模式可操作浏览器。
2026-03-04: English | 中文 — AgentTeams（彼时名为 HiClaw）开源，引入 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 获取技能（社区已有 80,000+ 个）。因为 Worker 本身就拿不到真实凭证，所以可以放心使用公开技能库。

快速开始

前置条件：Docker Desktop（Windows/macOS）或 Docker Engine（Linux）。若在 ECS 或云桌面等虚拟机上部署，请采用 Linux 系统，图形化需求，请使用 Ubuntu，官方镜像包暂不支持虚拟机上的 Window 系统，原因是虚拟机上的 Window 系统不是 Linux Container。

Docker Desktop（Windows / macOS）
Docker Engine（Linux）或 Podman Desktop（替代方案）

资源需求：最低 2C4GB 内存。如果希望部署较多 Worker 体验更强大的 Agent Teams 能力，建议 4C8GB 内存。目前 OpenClaw 内存占用较高。Docker Desktop 用户可在 Settings → Resources 中调整。

安装步骤：以下我们以最简单的本地部署、本地访问来演示安装步骤，不到5分钟就能开始玩龙虾了。

第一步：打开终端，Mac 系统输入以下安装命令。

bash <(curl -sSL https://higress.ai/hiclaw/install.sh)

Windows（建议 PowerShell 7+）输入以下安装命令：

Set-ExecutionPolicy Bypass -Scope Process -Force; $wc=New-Object Net.WebClient; $wc.Encoding=[Text.Encoding]::UTF8; iex $wc.DownloadString('https://higress.ai/hiclaw/install.ps1')

这里，输入 Mac 系统的安装命令。

第二步：选择语言，选择中文。

第三步：选择安装模式，快速开始请选择阿里云百炼快速安装。您也可以选择其他模型服务，手动配置。

第四步：选择大模型服务商。选择百炼，您也可以接入其他支持 OpenAPI 协议的模型服务，目前 Anthropic 协议还未支持，排期中。

第五步：选择模型接口。百炼 Coding Plan 和百炼通用接口有所不同，这里我们选择 Coding Plan 接口。购买Coding Plan

第六步：选择模型系列。如果第五步中选择的是百炼 Coding Plan，您可以选择 qwen3.5-plus、GLM等，待 Matrix room 建立起来后，还可通过发送指令，让 Manager 切换其他到模型。

第七步：开始测试 API 联通性，若测试成功，效果如下。

若测试不成功，您需要检查模粘贴的型 API Key是否完整或无空格，若再次尝试仍无法通过，建议像模型服务厂商提交服务工单。

第八步：选择网络访问模式。这里我们选择仅本机使用，若允许外部访问，例如和同事建立 Matrix roon，则选择允许外部访问。选择后，按回车键即可，确定端口号、网关主机端口、Higress 控制台主机端口、Maxtrix 域名、Element Web 直接访问的主机端口、文件系统域名等，均采用默认值，无须手动配置。

第九步：GitHub 集成、Skills 注册中心、数据持久化、Docker 卷、Manager 工作空间，按回车键即可，均采用默认配置，无须手动配置。

第十步：选择 Manager Worker 运行时，目前支持 OpenClaw 和 Copaw，未来还将支持 NanoClaw、ZeroClaw 等。

第十一步：等待安装。安装完成。登录密码是自动生成的。

若希望通过移动端来访问和使用，则需要使用美区账号下载 FluffyChat/Element Mobile。（之所以采用这两个 IM，是因为他们是支持 Matrix 协议的）下载后，连接您的 Matrix 服务器地址，就能随时随地管理您的 Agent 团队。

第十二步：浏览器中，输入 http://127.0.0.1:18088/#/login，登录 Element，输入用户名和密码，就可以玩龙虾了，告诉 Manager 创建 Worker 并分配任务。

⚠️ 注意：AgentTeams 内置了 Higress AI 网关，负责模型 API Key 管理以及入口流量的安全管控。模型 API Key 的切换、新增，以及路由、域名、证书管理，均可在 Higress 控制台管理。

升级

每次更新新版本，您在终端执行以下命令，即可原地升级，默认升级到最新版本：

bash <(curl -sSL https://higress.ai/hiclaw/install.sh)

就地升级，数据和配置会保留；全新重新，会删除所有数据。

若要升级到指定版本，请使用以下命令：

HICLAW_VERSION=v1.0.5 bash <(curl -sSL https://higress.ai/hiclaw/install.sh)

卸载

macOS / Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/higress-group/hiclaw/main/install/hiclaw-install.sh) uninstall

Windows (PowerShell):

Set-ExecutionPolicy Bypass -Scope Process -Force; $wc=New-Object Net.WebClient; $wc.Encoding=[Text.Encoding]::UTF8; $s=$wc.DownloadString('https://raw.githubusercontent.com/higress-group/hiclaw/main/install/hiclaw-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，无需额外依赖。

前置条件

Kubernetes 1.24+（kind / minikube / k3s / 各类托管 K8s 均可）
Helm 3.7+
默认 StorageClass（用于 Tuwunel 与 MinIO 的 PVC）

安装（OpenAI / OpenAI 兼容模式）

helm repo add higress.io https://higress.io/helm-charts
helm repo update

helm install hiclaw higress.io/hiclaw \
  -n hiclaw-system --create-namespace \
  --render-subchart-notes \
  --set credentials.llmApiKey=<你的-API-Key> \
  --set credentials.adminPassword=<你的-管理员密码> \
  --set gateway.publicURL=http://localhost:18080

如果使用非 OpenAI 但兼容 OpenAI API 的服务商，还需设置 llmBaseUrl：

helm install hiclaw higress.io/hiclaw \
  -n hiclaw-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）

helm install hiclaw higress.io/hiclaw \
  -n hiclaw-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 时留空
`manager.runtime`	可选	Manager Agent 运行时：`openclaw`（默认）、`copaw` 或 `hermes`
`worker.defaultRuntime`	可选	Worker 默认运行时：`openclaw`（默认）、`copaw` 或 `hermes`

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

helm install hiclaw higress.io/hiclaw \
  -n hiclaw-system --create-namespace --devel \
  --set manager.runtime=copaw \
  --set worker.defaultRuntime=hermes \
  --set credentials.llmApiKey=<your-api-key> \
  --set credentials.llmBaseUrl=https://your-provider.example.com/v1 \
  --set credentials.defaultModel=your-model-name \
  --set credentials.adminPassword=<your-admin-password> \
  --set gateway.publicURL=http://localhost:18080

各组件镜像会根据运行时自动选择（Manager: hiclaw-manager / hiclaw-manager-copaw；Worker: hiclaw-worker / hiclaw-copaw-worker / hiclaw-hermes-worker）。

多地域镜像仓库

默认 global.imageRegistry 指向中国区域（higress-registry.cn-hangzhou.cr.aliyuncs.com/higress）。如果在中国大陆以外部署，可切换至就近区域以加速镜像拉取：

区域	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`

# 示例：使用北美镜像仓库部署
helm install hiclaw higress.io/hiclaw \
  -n hiclaw-system --create-namespace \
  --render-subchart-notes \
  --set global.imageRegistry=higress-registry.us-west-1.cr.aliyuncs.com/higress \
  --set credentials.llmApiKey=<你的-API-Key> \
  --set credentials.adminPassword=<你的-管理员密码> \
  --set gateway.publicURL=http://localhost:18080

完整可配置项（网关/存储 provider、镜像 tag、资源、持久化等）请参考 helm/hiclaw/values.yaml。

访问

kubectl port-forward -n hiclaw-system svc/higress-gateway 18080:80

然后在浏览器中打开 http://localhost:18080 登录 Element Web。生产集群中请通过 Ingress / LoadBalancer / DNS 指向 svc/higress-gateway，并相应地修改 gateway.publicURL。

升级

helm repo update
helm upgrade hiclaw higress.io/hiclaw -n hiclaw-system --reuse-values

卸载

helm uninstall hiclaw -n hiclaw-system
kubectl delete namespace hiclaw-system

更深入的 K8s Native 架构说明（CRD、Controller、声明式 Worker / Team / Human 资源）请参考 docs/zh-cn/k8s-native-agent-orch.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）— 自主编程 Agent，具备终端沙箱、自我进化的 Skill 和持久化记忆

每种运行时各有擅长。推荐模式：用确定性更高的 Agent（OpenClaw/QwenPaw）做 Leader 负责任务分解和调度，用 Hermes Worker 执行自主编程任务。所有运行时通过 Matrix m.mentions 在同一个房间内通信——完全可见、随时可干预。

# 原地切换任意 Worker 的运行时
hiclaw update worker --runtime hermes

架构

┌───────────────────────────────────────────────┐
│            hiclaw-controller                  │
│  Higress │ Tuwunel │ MinIO │ Element Web      │
└──────────────────┬────────────────────────────┘
                   │ Matrix + HTTP Files
┌──────────────────┴──────────┐
│     hiclaw-manager-agent     │
│     Manager (OpenClaw/       │
│       QwenPaw)               │
└──────────────────┬──────────┘
                   │
┌──────────────────┼────────────────────────────┐
│                  │                            │
▼                  ▼                            ▼
Worker Alice    Worker Bob              Worker Charlie
(OpenClaw)      (QwenPaw)               (Hermes)

组件	职责
hiclaw-controller	Kubernetes 原生控制平面，协调 Worker/Team/Manager CR
Higress AI 网关	LLM 代理、MCP Server 托管、凭证管理
Tuwunel (Matrix)	自建 IM 服务器，承载所有 Agent + 人类通信
Element Web	浏览器客户端，零配置
MinIO	集中式文件存储，Worker 无状态

常见问题

如果 Manager 容器启动失败，执行以下命令查看具体原因：

docker exec -it hiclaw-manager cat /var/log/hiclaw/manager-agent.log

更多常见问题（启动超时、局域网访问等）参见 docs/zh-cn/faq.md。

提交 Bug

提交 Issue 前，建议先导出 Matrix 消息记录，用 AI 工具结合代码库分析问题根因，这能大幅加快修复速度。

# 导出调试日志（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 中。

你也可以让 AI 工具直接提交 Issue 或 PR。先安装 GitHub CLI，执行 gh auth login 在浏览器中完成登录，然后将 OpenClaw GitHub skill 配置到你的 AI 编程工具（Cursor、Claude Code 等）中。之后直接让它根据分析结果提交 Issue 或 PR 即可。

欢迎提交 Issue，或在 Discord / 钉钉群里随时提问。

文档


docs/zh-cn/quickstart.md	端到端快速入门，含验证检查点
docs/zh-cn/architecture.md	系统架构详解
docs/zh-cn/manager-guide.md	Manager 配置与使用
docs/zh-cn/worker-guide.md	Worker 部署与故障排查
docs/zh-cn/development.md	贡献指南与本地开发
docs/zh-cn/faq.md	常见问题

构建与测试

make build               # 构建所有镜像
make test                # 构建 + 运行全部集成测试
make test SKIP_BUILD=1   # 不重新构建，直接运行测试
make test-quick          # 快速冒烟测试（仅 test-01）

其他命令

# 通过 CLI 向 Manager 发送任务
make replay TASK="创建一个名为 alice 的前端开发 Worker"

# 卸载所有内容
make uninstall

# 推送多架构镜像
make push VERSION=0.1.0 REGISTRY=ghcr.io REPO=higress-group/hiclaw

make help  # 查看所有可用目标

社区

Discord
钉钉群
微信群--扫码加入：

许可证

Apache License 2.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

动态

为什么选 AgentTeams

快速开始

升级

卸载

Kubernetes 部署（Helm）

工作方式

Manager 是你的 AI 管家

安全模型

人工全程监督

AgentTeams vs OpenClaw 原生

多运行时协作

架构

常见问题

提交 Bug

文档

构建与测试

其他命令

社区

许可证

Uh oh!

FilesExpand file tree

README.zh-CN.md

Latest commit

History

README.zh-CN.md

File metadata and controls

动态

为什么选 AgentTeams

快速开始

升级

卸载

Kubernetes 部署（Helm）

工作方式

Manager 是你的 AI 管家

安全模型

人工全程监督

AgentTeams vs OpenClaw 原生

多运行时协作

架构

常见问题

提交 Bug

文档

构建与测试

其他命令

社区

许可证