AgentTeams 的核心价值，不是再造一个大模型 Agent 内核，而是把多个已经存在的 Agent runtime 组织成一个可见、可管、可审计的协作系统。它把人、Manager、Worker、Team、文件系统、模型网关和运行时容器放到同一张控制面里，让多 Agent 协作从“聊天窗口里的临时分工”变成“有身份、有房间、有状态、有存储、有生命周期”的操作系统。
这套系统最有意思的地方在于它承认现实：不同 Agent runtime 有不同优势。OpenClaw 适合做多渠道、多房间、多技能的协调入口；QwenPaw/CoPaw 可以承担另一类 Python 运行时和团队领导者角色；Hermes 更像自治执行型 Worker，适合在隔离容器里完成代码、自动化和长任务。AgentTeams 站在它们上方，提供协作协议、控制面和基础设施，把“谁负责协调、谁负责执行、谁能看到什么、结果放在哪里、什么时候启动或休眠”这些问题系统化。
因此，AgentTeams 更接近一个协作型 Multi-Agent OS：Matrix 是消息总线和审计时间线，Tuwunel 是房间服务器，Element 是人类可见界面，Higress 是 LLM/MCP/API 网关，MinIO/OSS 是共享文件系统，Controller 是声明式控制面，Manager 是调度员，Worker 是执行单元，Team 是层级化协作组织。
定位：多 Agent 协作操作系统，而不是单体 Agent
传统 Agent 项目通常从一个“智能体大脑”开始：定义提示词、工具、记忆、模型和执行循环。AgentTeams 的切入点不同，它从协作系统开始：先定义人类、Manager、Worker 和 Team 的关系，再把不同 runtime 装进容器，通过统一的房间、凭据、文件和控制接口连接起来。
这种定位带来三个直接结果。第一，AgentTeams 不需要押注某一个 Agent 内核永远胜出。OpenClaw、QwenPaw、Hermes 可以共存，runtime 只是 Worker 或 Manager 的实现方式。第二，协作过程天然可见。任务分配、追问、阻塞、结果通知都发生在 Matrix 房间，人类可以旁观，也可以随时介入。第三，状态不完全依赖上下文窗口。任务说明、计划、进度、结果、技能和运行时配置被写入对象存储，即使 Agent 会话重置，也能从文件恢复。
这解决的是多 Agent 工程化里最常见的几个痛点：临时拉起的 Agent 容易失联；上下文断掉后无法恢复；不同 Agent 之间缺少共享状态；工具凭据容易泄漏；人类只看到最终结论，看不到过程；多个 Worker 的生命周期和成本不可控。AgentTeams 用平台层把这些问题收束起来。
总体架构：控制面、协作面、数据面和运行时
AgentTeams 的架构可以拆成四层。
第一层是人类交互层。用户通过 Element Web 或其他接入渠道和 Manager、Worker、Team 房间沟通。这里的关键不是“聊天”，而是把人类监督变成一条可审计时间线：每个任务如何被分配，谁提出问题，谁批准执行，谁报告完成，都能在房间里追溯。
第二层是协作通信层。Tuwunel 提供 Matrix homeserver，所有 Agent 都有自己的 Matrix 身份。Manager 与 Human 有 DM，Manager 与 Worker 有专属 Worker Room，Team 有 Team Room，Team Leader 还可能拥有和 Team Admin 的 Leader DM。@mention 不是礼貌动作，而是唤醒协议：只有被明确点名的 Agent 才应该处理任务，避免多 Agent 房间里互相误触发。
第三层是控制面。agentteams-controller 是 Go 编写的 operator 与 REST API 服务。它维护 Worker、Manager、Team、Human 等 CRD，负责 reconcile、创建账号、生成凭据、创建房间、写入配置、调度容器、暴露服务、刷新状态。`agt` CLI 和 Manager 的管理技能最终都应该通过这个控制面做资源变更，而不是手写临时命令。
第四层是数据面与运行时层。MinIO/OSS 存放 `agents/
控制面：CRD + Reconciler + REST API
AgentTeams 的工程内核在 `agentteams-controller`。它不是一个简单的脚本集合，而是 Kubernetes controller-runtime 风格的应用容器：启动时初始化 scheme、基础设施客户端、controller manager、backend registry、字段索引、鉴权中间件、服务层、各类 reconciler 和 HTTP server。启动后，HTTP API、初始化器、远端客户端维护、凭据清理和 controller manager 并行运行。
CRD 是系统的声明式入口。WorkerSpec 包含模型、runtime、镜像、身份、SOUL、AGENTS、技能、远程技能、MCP Server、包、端口暴露、channelPolicy、资源、空闲超时、生命周期状态、AccessEntry、AgentIdentity、CredentialBinding、deployMode、serviceEnabled、backendRuntime、Pod labels、volumes 和 mounts。Manager、Team、Human 也各有资源模型。用户要表达的是“我想要什么样的 Agent 成员”，Controller 负责把它收敛成真实的账号、房间、文件、网关消费者和容器。
REST API 是命令式入口。`/api/v1/workers`、`/api/v1/teams`、`/api/v1/humans`、`/api/v1/managers` 提供 CRUD；`wake`、`sleep`、`ensure-ready`、`ready`、`status` 提供生命周期控制；Gateway endpoint 管消费者；Credentials endpoint 发放 STS 和 Matrix token；Matrix AppService endpoint 接收 homeserver 事件；嵌入式模式下还有受安全校验保护的 Docker API passthrough。
这意味着 AgentTeams 同时支持两种使用姿势：人可以在 Matrix 中让 Manager 创建 Worker，也可以用 `agt create worker` 或 YAML 直接声明资源。前者适合日常协作，后者适合自动化、CI、Kubernetes 和平台集成。
Worker 生命周期：从声明到可执行容器
Worker 创建流程体现了 AgentTeams 的平台化程度。一个 Worker 从 CR 或 Manager 指令进入系统后，控制器先进入 infrastructure phase：加载或生成凭据，注册 Matrix 账号，必要时创建 MinIO 用户和策略，创建或解析 Worker 房间，邀请 admin、manager、worker，设置 power level，再创建 Higress consumer 和 key-auth 绑定。
接着是 config phase。Deployer 会部署包、写入 inline identity/soul/agents、生成 `openclaw.json`、合并 AGENTS.md、写入 SOUL.md、配置 mcporter、推送内置技能，并把文件同步到对象存储。对于 QwenPaw 或 Edge/remote-managed local 这类运行时，控制器还会写 `agents/
最后是 container phase。Controller 根据 desired state 决定 Worker 应该 Running、Sleeping 还是 Stopped。Docker backend 通过 Docker Engine API 创建容器，Kubernetes backend 创建 Pod 并挂载 service account token。spec 变更会触发删除旧资源再重建，睡眠状态会停止或删除容器，edge worker 则跳过托管 Pod，只保留凭据和 runtime.yaml 这类远端运行需要的控制信息。
这个设计的重点是幂等。WorkerReconciler 并不假设一次命令一定成功，而是不断观察现实状态与期望状态的差异：房间没建好就重试，配置没写完就继续写，容器缺失就创建，spec hash 不一致就重建，状态进入 transient 就等待下一轮事件或周期 reconcile。多 Agent 平台要长时间运行，幂等比“演示时能跑通”更重要。
Manager：调度员、记忆入口和系统管理员
Manager 是 AgentTeams 的协调中心。它不是所有任务的执行者，而是把人类目标转化为资源创建、任务登记、文件准备、Worker 唤醒、房间通知、结果收集和状态更新的调度员。
Manager 的系统文件主要是 `SOUL.md`、`HEARTBEAT.md` 和 `AGENTS.md`。内置技能覆盖 channel management、file sync、git delegation、worker/team/human management、MCP server management、model switch、project management、task coordination、task management、service publishing 等。这里体现了 AgentTeams 的设计哲学：Manager 不应该用零散自然语言“凭感觉管理”，而应该通过技能和 CLI 调用控制面。
Manager 的 `AGENTS.md` 里把很多协作规则写得非常工程化：创建多个 Worker 时要并行发起 `agt create worker --no-wait`；给 Worker 分配任务必须在 Worker Room 或 Project Room 里真正 @mention，而不能只在 admin DM 中说“已分配”；任务必须登记到 `state.json`，否则 idle timeout 可能把 Worker 停掉；Worker 完成后不能只口头确认，必须拉取任务目录、读 result、更新 meta/state、写 memory、通知 admin。
这种规则看似繁琐，本质上是在把多 Agent 协作从“聊天即执行”拉回“有状态的工作流”。Manager 的价值不在于永远亲自完成任务，而在于让每一个任务都有编号、有目录、有负责人、有进度、有结果、有恢复路径。
Worker Runtime：OpenClaw、QwenPaw/CoPaw 与 Hermes
Worker 是轻量、相对无状态的执行容器。它们连接 Matrix，拉取 MinIO/OSS 中的配置和共享数据，通过 AI Gateway 访问模型，通过 mcporter 调 MCP Server，通过本地工作区产生结果，再把结果同步回共享文件系统。
OpenClaw Worker 采用 `/root/agentteams-fs/agents/
QwenPaw/CoPaw Worker 更偏 Python runtime。CoPaw 有 standard/lite 模式，QwenPaw 把工作目录设在 `/root/agentteams-fs/agents/
Hermes Worker 的入口明确把 HOME、workspace 和 MinIO mirror root 对齐到 `/root/agentteams-fs/agents/
OpenClaw 与 Hermes 的协作关系
OpenClaw 与 Hermes 在 AgentTeams 中不是二选一关系，而是上下游协作关系。AgentTeams 把 runtime 差异藏在 Worker 规格、镜像、入口脚本、工作区布局和 runtime config 里，对协作层暴露的是统一身份、统一房间、统一文件目录、统一任务约定和统一生命周期。
OpenClaw 的优势在协调：多渠道、Matrix 插件、技能目录、房间协议、heartbeat、任务状态、控制 UI 和 Manager/Leader 工作流都更适合做“组织者”。一个 OpenClaw Manager 可以接收人类需求，拆解任务，选择 Worker，创建项目房间，准备共享文件，@mention Worker，追踪结果，必要时升级给人类。
Hermes 的优势在执行：它更适合在容器内完成相对独立的开发、自动化、工具调用和长周期任务。它不需要成为系统唯一入口，也不需要承担所有协调规则；只要能读取任务目录、使用模型与工具、把产物写回共享空间，并在房间里报告完成，就能作为高自治 Worker 嵌入 AgentTeams。
这是一种很务实的组合：用 OpenClaw/QwenPaw 这类更确定的协调 runtime 当 Manager 或 Team Leader，用 Hermes 这类自治执行 runtime 当 Worker，AgentTeams 负责“组织协作”。当 Agent 内核还在快速迭代时，把协作协议、身份、文件、网关和生命周期放在平台层，会比把所有能力塞进一个超大 Agent 更稳。
Team：从扁平 Worker 池到层级协作组织
单 Manager 管多个 Worker 容易形成瓶颈。Team 资源把协作层级化：Team 有 Leader、Workers、Admin、Human Members、Team Room、Leader DM 和 per-worker rooms。TeamReconciler 会解析 Human 身份，把有权限的人加入团队上下文，并同步人类房间状态。
控制器还会把 Coordination block 注入 AGENTS.md。Leader 会知道上游 coordinator 是 Manager，Team Admin 是谁，Team Room 在哪里，Worker 列表和房间 ID 是什么，heartbeat 间隔和 idle timeout 是什么；Worker 会知道自己的 coordinator 是 Team Leader，不能直接 @mention Manager，完成、阻塞和问题都要报给 Leader。
这解决了多 Agent 规模化中的一个关键问题：协作拓扑不能靠 Agent 自己猜。谁能分配任务、谁能做决策、谁向谁汇报、哪些人可以 @mention Worker，都应该成为运行时提示词和配置的一部分。AgentTeams 用 Team CRD 和 Coordination injection 把这些关系写成可管理的系统事实。
共享文件系统：比上下文窗口更可靠的协作记忆
多 Agent 协作不能只依赖对话历史。AgentTeams 把持久状态放在 MinIO/OSS：Manager 配置在 `agents/manager/`，Worker 配置在 `agents/
这种设计有三个好处。第一，任务上下文可以恢复。Worker 会话重置后，可以读取 task-history、spec、plan 和 progress 重新接上。第二，文件是跨 runtime 的最低共同协议。OpenClaw、QwenPaw、Hermes 都能读写文件，不必共享同一个内存系统。第三，审计更清楚。房间记录“谁说了什么”，对象存储记录“任务文件和产物是什么”，两者合在一起才是真正可追踪的协作日志。
文件同步策略也体现了工程经验。OpenClaw Worker 不再简单依赖 `mc mirror --watch`，而是用变更检测推送 Worker 管理内容，对 Manager 管理的 openclaw.json、mcporter 配置和 skills 做周期拉取和按需同步，避免刚拉下来的配置被本地旧文件反向覆盖。对多 Agent 系统来说，文件所有权和同步方向必须清晰，否则很容易出现配置互相覆盖。
网关、凭据与安全边界
AgentTeams 把 LLM 与 MCP 访问集中到 Higress AI Gateway。每个 Worker 对应 gateway consumer 和 key-auth，控制器把模型 provider、MCP Server endpoint 和 Authorization header 写进配置或 runtime.yaml。这样，Worker 不需要直接拿到平台全局 API Key，而是使用自己的 consumer key 和授权范围访问模型与工具。
CRD 里还把 AccessEntry、AgentIdentity、CredentialBinding 作为一等字段。AccessEntry 描述对象存储、AI gateway、AI registry、scheduler 等服务权限；AgentIdentity 提供工作负载身份事实；CredentialBinding 只引用凭据 provider，不携带真实 secret，并允许配置 tool whitelist。这是把“Agent 能访问什么”从提示词约束推进到平台资源模型。
Matrix 也承担安全边界。房间邀请、allowlist、power level、@mention 协议和 Matrix token 控制了谁能向 Agent 发送有效消息。Manager 侧还明确要求敏感信息不要通过聊天消息泄露，凭据通过文件系统和控制器流转。
这套安全模型不是完美终局，但方向正确：多 Agent 平台不能把安全只写进系统提示词。身份、凭据、网关授权、对象存储前缀、ServiceAccount token、房间权限和工具白名单，必须在平台层共同约束。
部署拓扑：本地嵌入式与 Kubernetes
本地嵌入式部署把 Higress、Tuwunel、MinIO、Element Web 和 controller 运行在 `agentteams-controller` 容器中，Manager 单独运行，Worker 由 Controller 或 Manager 通过 Docker socket 拉起。这适合个人开发、演示、小团队本机使用，优点是启动快、依赖少、可直接在 Element 里看到协作过程。
Kubernetes 部署则更接近生产形态：Higress 作为子 chart，Tuwunel StatefulSet，MinIO 或 OSS，Element Web，controller Deployment，Manager/Worker 由 CRD 驱动创建 Pod。K8s backend 会使用 in-cluster config 或 kubeconfig，给 Pod 挂载 projected service account token，设置 owner reference，让 CR 删除能触发 Kubernetes 垃圾回收。
两种拓扑的核心差异不是功能多少，而是控制边界。本地模式更像一体化开发环境，Kubernetes 模式更像平台工程：资源限制、service account、命名空间、PodTemplate overlay、网关和对象存储都需要更严格治理。文章级理解可以把它们视为同一个控制面在不同基础设施 backend 上的落地。
模块拆解：每一层各司其职
按代码模块看，AgentTeams 的职责边界比较清晰。
`agentteams-controller/api/v1beta1` 定义资源模型和契约，包括 Worker、Manager、Team、Human 以及 AccessEntry、MCPServer、RemoteSkillSource、CredentialBinding 等字段。它决定平台能声明什么。
`internal/app` 负责应用装配：基础设施客户端、backend、auth、service layer、reconciler 和 HTTP server 都在这里接线。它决定控制器如何启动。
`internal/controller` 负责声明式收敛。WorkerReconciler、ManagerReconciler、TeamReconciler、HumanReconciler 分别处理不同 CR，member_reconcile 把 Worker 与 Team member 的通用流程抽出来，避免 standalone Worker 和 Team Worker 各走一套逻辑。
`internal/service` 是平台操作层。Provisioner 管 Matrix、Gateway、MinIO、ServiceAccount 和端口暴露；Deployer 管配置生成、包部署、AGENTS 合并、技能推送、runtime.yaml 写入；EnvBuilder 管容器环境变量。
`internal/backend` 抽象运行实例。Docker backend 管本地容器，Kubernetes backend 管 Pod，sandbox backend 是更高级隔离形态的入口；runtime resolution 在这里统一处理 explicit runtime、caller fallback 和 openclaw 默认值。
`manager/agent/skills` 是 Manager 的操作手册库，负责把“如何创建 Worker、如何管理任务、如何同步文件、如何发布服务、如何切换模型”变成可复用技能。`worker/scripts`、`hermes/scripts`、`copaw/scripts`、`qwenpaw/scripts` 则是不同 runtime 的容器入口，把平台凭据和文件系统契约翻译成具体 Agent 进程。
TeamHarness：插件化协作语义的预演
AgentTeams 还在推进 TeamHarness 这类 runtime-neutral 插件包。它的边界很明确：提供团队协作提示词、角色提示词、组织/沟通/文件共享/项目管理/任务委派/任务执行等技能，以及 message、filesync、projectflow、taskflow 等 MCP 工具；但不负责 Worker 生命周期、Controller reconcile、runtime desired-state apply loop、凭据值存储或周期性文件同步。
这个边界很重要。AgentTeams 的主平台负责“资源和生命周期”，TeamHarness 负责“协作语义和工具包”，具体 runtime adapter 负责“把这些语义落到 QwenPaw、Claude Code 或其他运行时”。如果这三层混在一起，插件会变成小型控制器，runtime 会偷偷管理平台资源，系统边界会迅速失控。
更长远看，AgentTeams 的协作能力可能会从 Manager 技能逐步沉淀到 TeamHarness 这类插件契约中。控制器继续写 runtime.yaml，runtime adapter 读取 desired state，TeamHarness 提供统一协作工具。这样，多 Agent OS 才能真正支持更多 runtime，而不是围绕某一个 Agent 内核写死。
完整工作流：一个任务如何被执行
一次典型任务可以这样理解。
人类先在 Manager DM 或 Team Admin 入口提出目标。Manager 判断是否需要新建 Worker 或使用已有 Worker。如果需要新建，它通过 `agt` 或技能创建 Worker CR，控制器完成账号、房间、网关、存储、配置和容器创建。Worker Ready 后，Manager 在共享文件系统中写入任务目录，包括 meta、spec、plan 或必要输入文件。
随后 Manager 在正确房间 @mention Worker 或 Team Leader。Worker 收到 Matrix 消息后拉取任务文件，执行任务，把中间进度写到 `shared/tasks/
Manager 收到完成通知后，不应该只发一句“收到”。正确流程是拉取任务目录、读取 result、更新 meta.json 和 state.json、写 memory、必要时通知人类、归档或继续下一步。整个过程中，人类可以在 Element 中看到消息时间线，也可以直接介入问题、批准敏感动作、调整任务范围。
这个流程把 Agent 的“智能执行”嵌入到“工程化协作”里。前者决定任务能否做成，后者决定任务能否被管理、恢复、审计和规模化。
核心优势：透明、可插拔、可恢复、可治理
AgentTeams 最大的优势是透明。传统后台 Agent 任务一旦跑起来，人类往往只能等最终结果；AgentTeams 把协作放进房间，过程天然可见。透明不是为了好看，而是为了干预和审计。
第二个优势是 runtime 可插拔。OpenClaw、QwenPaw、Hermes 可以在同一个房间体系和对象存储体系中协作，平台不被单一 Agent 内核绑定。Agent 技术迭代太快，平台层越中立，长期越有韧性。
第三个优势是可恢复。任务文件、进度日志、task history、runtime config 和共享目录让系统不完全依赖模型上下文。session reset、容器重启、Worker 睡眠后再唤醒，都不必从零开始。
第四个优势是可治理。CRD、REST API、ServiceAccount、Gateway consumer、Matrix identity、对象存储前缀、AccessEntry、CredentialBinding、channelPolicy 让平台可以逐步把权限和生命周期收束到可管理模型里。
边界与风险：复杂度来自真实协作
AgentTeams 的复杂度不低。Matrix、Higress、MinIO/OSS、Controller、Manager、Worker、runtime entrypoint、技能、对象存储同步、gateway auth、Kubernetes/Docker backend 共同组成系统，排障要求比单体 Agent 高得多。
第二个风险是 runtime 差异。OpenClaw 使用 openclaw.json 和 Matrix 插件，QwenPaw/Hermes 逐步使用 runtime.yaml 契约，CoPaw 又有不同安装目录和 console 模式。平台虽然抽象了 runtime，但每个 runtime 的文件布局、热加载能力、审批模型、日志和工具行为仍然不同。
第三个风险是协作纪律。@mention 协议、任务登记、文件先推送再通知、Worker 完成后必须读 result 并更新 state，这些流程如果被 Manager 或技能违反，系统仍会卡住。多 Agent 平台不是只靠模型更强就能自动正确，流程约束必须持续打磨。
第四个风险是生产安全。YOLO Worker、Docker socket、本地 host-share、MCP 工具、模型网关和凭据流转都需要严格边界。AgentTeams 已经把很多边界放到平台层，但生产落地仍要结合网络隔离、最小权限、日志审计、敏感数据策略和人工审批机制。
适用场景：什么时候值得引入 AgentTeams
如果只是让一个 Agent 帮忙写一段代码、查一个问题、处理一个简单文件，单体 Agent 足够。AgentTeams 的价值出现在更复杂的场景：需要多个 Worker 并行处理任务；需要人类实时旁观和介入；需要长期任务恢复；需要不同 runtime 协作；需要统一管理模型、MCP、凭据和文件；需要把任务执行过程留痕。
典型场景包括：研发团队把需求拆给多个 coding worker；运维团队让不同 Worker 处理监控、日志、修复和报告；数据团队让 Worker 并行清洗、分析、制图和写报告；企业内部把不同部门的工具通过 MCP 暴露给 Agent；个人高级用户把 Hermes、OpenClaw、QwenPaw 等不同执行器组织成一个可控工作台。
简单说，AgentTeams 不适合把简单任务复杂化，但适合把复杂协作标准化。
结论：AgentTeams 的价值在“组织智能”
AgentTeams 的长期价值不在于某个单点模型调用，也不在于某个 Worker runtime 的即时能力，而在于它把 Agent 协作中的组织问题工程化了。身份、房间、@mention、任务目录、结果文件、技能、网关、权限、生命周期、状态恢复，这些看似琐碎的东西，恰恰是多 Agent 从演示走向日常工作的关键。
OpenClaw 与 Hermes 的关系也应该放在这个框架下理解：OpenClaw 更适合成为协调入口和团队 Leader，Hermes 更适合作为自治执行 Worker；AgentTeams 则提供让它们协作的操作系统层。未来 Agent runtime 还会不断变化，但只要人类监督、多 Agent 分工、共享文件、工具权限和任务恢复仍是刚需，AgentTeams 这种控制面优先的架构就有持续价值。