OpenClaw专家智能体编排框架：一键部署多领域AI专家团队-程序员充电站

1. 项目概述：为OpenClaw构建专家级智能体编排框架

如果你正在使用OpenClaw，并且厌倦了手动配置每一个专业智能体来处理不同的任务，比如代码审查、安全审计、架构评审，那么agencyteam-openclaw这个项目可能就是你在寻找的“自动化团队管家”。简单来说，它不是一个全新的AI模型，而是一个专家智能体编排框架。它的核心价值在于，能将上游一个公开的专家智能体名录（agency-agents），自动、批量地转换并集成到你的OpenClaw环境中，让你一键拥有一个分工明确、各司其职的“AI专家小组”。

想象一下，你提交了一段新代码。传统上，你可能需要自己扮演代码审查员、安全工程师、产品经理等多个角色，或者手动切换不同的智能体。而有了agencyteam，你可以同时或按需调度“代码审查专家”、“安全审计专家”、“UI设计师”等多个专业智能体，对同一份材料进行并行评审，最后综合他们的意见。这尤其适合开发者、技术负责人、产品经理等需要高质量、多维度AI辅助的从业者，它能将零散的人工智能体管理工作，转化为可重复、可版本化的自动化工作流。

2. 核心设计思路与架构解析

2.1 核心理念：从“单体助手”到“专家小组”

OpenClaw本身是一个强大的AI智能体平台，但默认情况下，用户需要自行创建和维护每一个智能体（Agent）及其对应的工作空间（Workspace）。当任务涉及多个专业领域时，手动管理这些智能体变得繁琐且容易出错。agencyteam的核心理念是引入“编排”（Orchestration）的概念，将上游预定义的、高质量的专家提示词（Prompts）资源，通过标准化的流程，转化为OpenClaw本地可用的、立即可用的专家智能体。

这背后的设计哲学是“关注点分离”和“基础设施即代码”。项目维护者siubing05并不直接创造专家智能体的内容（那是上游agency-agents项目的工作），而是专注于创造一套可靠的“转换-安装-同步”工具链。这样做有几个显著优势：

职责清晰：上游负责专家能力的定义和质量；agencyteam负责部署和生命周期管理。
可重现性：通过固定上游代码库的特定版本（UPSTREAM_REF），确保每次安装都能得到完全一致的专家智能体集合，避免了因上游更新带来的意外行为变化。
非侵入式集成：它不会覆盖或干扰你已经在OpenClaw中手动创建的其他智能体，实现了新老智能体的和平共处。

2.2 技术架构与工作流拆解

整个框架的运行可以清晰地分为三个阶段：转换、安装/更新、运行。

第一阶段：转换（Conversion）这是将上游“原材料”加工成OpenClaw可识别的“零件”的过程。核心脚本是./scripts/convert.sh。它的工作流程如下：

获取源材料：脚本会克隆（或更新）指定的agency-agents上游仓库到一个临时目录。默认情况下，它会使用项目内定义的UPSTREAM_REF（一个固定的Git提交哈希或标签），以确保转换的可重现性。
解析与转换：脚本遍历上游仓库中特定目录结构下的专家定义文件（通常是Markdown文件，包含了系统提示词、配置参数等）。它会解析这些文件，提取出智能体的名称、ID、描述以及最核心的系统提示词。
生成工作空间：根据解析出的信息，在本地一个暂存区域（Staging Area）创建符合OpenClaw规范的目录结构（~/.openclaw/agency-agents/<agent-id>/）。每个目录下会生成一个openclaw.json配置文件，其中最关键的部分就是嵌入了从上游提取的专家级系统提示词。同时，还会生成一个AGENTS.md文件作为该智能体的说明文档。

注意：转换阶段只是在暂存区生成文件，并不会立即影响你正在运行的OpenClaw实例。这提供了一个安全缓冲区，允许你在正式安装前预览将要发生的变化。

第二阶段：安装与同步（Installation & Synchronization）这是将“零件”安装到“机器”并接上“电路”的过程。核心脚本是./scripts/install.sh或./scripts/update.sh。

文件同步：将暂存区中生成好的专家智能体工作空间目录，复制到OpenClaw的正式工作空间根目录下。
配置注册：调用一个Python脚本（sync_openclaw_config.py）来修改OpenClaw的核心配置文件。这里主要做两件事：
- 更新agents.list：这个文件列出了所有可用的智能体。脚本会将新安装的专家智能体ID追加进去。
- 更新openclaw.json中的main.subagents.allowAgents：这个配置项决定了主智能体可以调用哪些子智能体。脚本会采用“合并”策略：如果当前配置是通配符['*']，则保持不变；否则，会将新安装的智能体ID列表合并到现有数组中，并去重。
安全备份：在修改任何配置文件之前，脚本会自动创建一个带有时间戳的备份文件（例如openclaw.json.backup.20250415_102030）。这是一个非常贴心的设计，为误操作提供了回滚的可能。
服务重启：为了使配置生效，脚本会尝试重启OpenClaw的网关（Gateway）服务，并等待其重新响应。这确保了安装后智能体立即可用。

第三阶段：按需运行（On-Demand Execution）当专家智能体就绪后，你可以通过OpenClaw的标准命令或agencyteam提供的便捷脚本来调用他们。./scripts/spawn-and-install.sh是一个特色脚本，它实现了“懒加载”模式：当你请求一个专家时，如果发现它尚未安装，脚本会先自动执行安装流程，然后再启动该智能体执行任务。这对于探索性使用或临时需要某个专家的情况非常高效。

整个架构通过清晰的目录隔离（暂存区 vs 运行区）、原子化的脚本操作和谨慎的配置合并策略，在提供强大自动化能力的同时，最大程度地保障了用户现有环境的稳定性和安全性。

3. 从零开始：详细安装与配置指南

3.1 环境准备与前置检查

在开始之前，请确保你的系统满足以下基础要求：

OpenClaw：必须已安装并可以正常运行。你可以通过运行openclaw --version来验证。
Git：用于克隆agencyteam项目本身以及上游的agency-agents仓库。
Python 3：项目中的配置同步脚本依赖Python环境。

建议在安装前，先检查一下你的OpenClaw当前状态：

# 查看当前已有哪些智能体 openclaw agents list # 检查网关服务是否健康 openclaw gateway status

记录下当前的智能体列表，以便和安装后的结果进行对比。

3.2 完整安装流程逐步解析

接下来，我们执行标准的完整安装。这个过程会安装所有agencyteam当前支持的专家智能体。

克隆项目到OpenClaw技能目录项目推荐将自身克隆到OpenClaw的工作空间技能目录下，这样管理起来更规整。
```
git clone https://github.com/siubing05/agencyteam-openclaw.git \ ~/.openclaw/workspace/skills/agencyteam
```
这个命令创建了一个~/openclaw/workspace/skills/agencyteam/目录，所有脚本和资源都位于此处。
执行安装脚本进入目录并运行安装脚本。
```
cd ~/.openclaw/workspace/skills/agencyteam ./scripts/install.sh
```
此时，脚本会开始执行我们在架构解析中描述的所有步骤。你会在终端看到一系列输出信息：
- “Cloning upstream...” - 正在克隆上游仓库。
- “Converting experts...” - 正在转换专家提示词。
- “Syncing config...” - 正在同步OpenClaw配置。
- “Backing up config...” - 正在备份你的配置文件。
- “Restarting gateway...” - 正在重启网关服务。
- “Waiting for gateway...” - 等待网关服务恢复。
整个过程可能需要一两分钟，取决于网络速度和上游仓库的大小。请耐心等待脚本执行完毕，不要中途中断。
验证安装结果安装脚本运行完成后，强烈建议进行验证。
```
# 再次列出智能体，应该能看到新增了许多以`agency-agents/`开头的专家 openclaw agents list # 确认网关运行正常 openclaw gateway status
```
你应该能在智能体列表中看到诸如agency-agents/engineering-code-reviewer,agency-agents/product-manager等新的ID。

3.3 选择性安装与高级配置

你可能不需要所有专家，或者想先体验几个核心角色。agencyteam提供了灵活的安装选项。

安装特定专家假设你只关心代码审查和安全审计，可以这样操作：

./scripts/install.sh --agents “engineering-code-reviewer engineering-security-engineer”

脚本会精确地只安装你指定的这两个专家智能体，并将其注册到配置中。

理解安装目录结构安装后，你的OpenClaw目录结构会发生变化：

~/.openclaw/ ├── openclaw.json (主配置文件，已被修改) ├── agents.list (智能体列表文件，已被追加) └── agency-agents/ (这是`agencyteam`管理的专家智能体根目录) ├── engineering-code-reviewer/ │ ├── openclaw.json (包含专家系统提示词) │ └── AGENTS.md (说明文档) ├── engineering-security-engineer/ └── ...

所有由agencyteam安装的专家智能体都整齐地放在~/.openclaw/agency-agents/下，与你手动创建的智能体（通常在其他位置）隔离开，便于管理。

环境变量覆盖对于高级用户，脚本行为可以通过环境变量定制：

AGENCY_DEST：指定上游仓库克隆到的临时目录路径。
OPENCLAW_CONFIG_PATH：指定OpenClaw配置文件的位置（如果你使用了非默认路径）。
AGENCYTEAM_UPSTREAM_REF：覆盖默认的上游版本，指向特定的Git标签或提交哈希。谨慎使用，除非你明确需要更新到新版本或回退到旧版本。
```
# 示例：使用特定的上游提交进行安装 AGENCYTEAM_UPSTREAM_REF=v1.2.0 ./scripts/install.sh --agents “engineering-code-reviewer”
```

4. 日常使用：工作流构建与专家调度

4.1 构建并行评审工作流

安装完成后，你就可以开始构建强大的多专家工作流了。最典型的场景是并行评审。假设你刚写完一个功能模块的代码，并编写了对应的API文档，你想同时获得代码质量、安全性和产品角度的反馈。

你可以在OpenClaw中创建一个“协调员”智能体，或者直接使用主智能体，通过subagents功能来调度专家小组。以下是一个概念性的操作思路（具体提示词需根据你的OpenClaw版本调整）：

准备评审材料：将你的代码文件、文档或需求描述整理在一个文本中。
设计协调提示词：给你的主智能体一个明确的指令，例如：
“我有一段新的代码和功能描述，需要组织一次专家评审。请你协调三位专家：代码审查员（agency-agents/engineering-code-reviewer）、安全工程师（agency-agents/engineering-security-engineer）和产品经理（agency-agents/product-manager）。将我的材料分别发送给他们，要求他们从各自专业角度提供评审意见，最后请你汇总一份包含关键问题、风险和建议的综合报告给我。”
执行与交互：将上述提示词和材料提交给主智能体。OpenClaw的subagents机制会自动将任务分发给对应的专家智能体，并收集他们的回复。

这种模式将你从手动切换不同聊天窗口、重复粘贴材料的繁琐工作中解放出来，实现了评审流程的自动化串联。

4.2 使用按需安装脚本

spawn-and-install.sh脚本是agencyteam的一大亮点，它完美解决了“专家智能体那么多，我难道要全装上？”的顾虑。

场景：你正在处理一个涉及前端UI的设计稿评审，但你之前只安装了工程类的专家。此时，你需要design-ui-designer（UI设计师）这位专家的意见。

传统做法：你需要中断当前工作，手动运行安装命令，等待安装完成，然后再去调用该智能体。

使用spawn-and-install.sh：

./scripts/spawn-and-install.sh design-ui-designer “请评审附件的设计稿，评估其用户体验、一致性和视觉层次。” --timeout 300

这个命令会：

检查design-ui-designer智能体是否存在。
如果不存在，则自动触发针对该智能体的安装流程（包括转换、配置同步等）。
安装成功后，立即使用给定的提示词启动该智能体，并设置300秒的超时时间。
将智能体的输出直接返回到终端。

实操心得：

--timeout参数非常有用，可以防止因智能体思考时间过长而导致的进程挂起。根据任务复杂度合理设置，简单任务120-180秒，复杂任务300-600秒。
这个脚本本质上是install.sh和openclaw spawn命令的智能组合。它非常适合在编写自动化脚本或探索性对话中使用，让你可以“即用即装”，保持本地环境的精简。

4.3 专家智能体的更新与维护

上游的agency-agents项目会不断优化和新增专家提示词。agencyteam提供了安全的更新机制。

1. 干运行预览在应用任何更新之前，强烈建议先进行干运行（Dry Run），查看将会发生哪些变化。

./scripts/update.sh --dry-run

这个命令会执行转换步骤（使用最新的默认UPSTREAM_REF或你指定的版本），并列出将会被添加、更新或删除（如果使用--prune-removed）的专家智能体，但不会实际修改你的OpenClaw配置和文件。这是避免意外的最佳实践。

2. 执行更新确认预览结果符合预期后，执行更新：

./scripts/update.sh

此命令会：

获取上游最新版本（或指定版本）的专家定义。
更新暂存区的工作空间文件。
将更新后的文件同步到正式的~/.openclaw/agency-agents/目录，覆盖之前由agencyteam生成的文件。
更新agents.list和openclaw.json中的相关配置。

3. 清理已移除的专家如果上游某个专家被移除了，而你希望本地环境也同步移除，可以使用--prune-removed选项：

./scripts/update.sh --prune-removed

重要警告：此操作会删除本地对应的专家智能体目录。请确保你不再需要该专家，或者在执行前已做好备份。脚本只会删除由agencyteam管理的目录（通过内部标记识别），你手动创建的其他目录是安全的。

更新策略的核心原则：

可重现性优先：默认使用固定的UPSTREAM_REF，这意味着常规的./scripts/update.sh并不会拉取“最新”的代码，而是拉取项目锁定的那个版本。要更新到上游真正的“最新”，你需要显式地覆盖AGENCYTEAM_UPSTREAM_REF环境变量（例如指向main分支的HEAD）。
用户修改不保留：如果你手动修改了~/.openclaw/agency-agents/engineering-code-reviewer/openclaw.json文件，更新过程会覆盖你的修改。因为这些文件被视为由agencyteam工具链管理。如果需要自定义专家，更安全的做法是基于这些专家复制一份到其他目录，然后修改副本。

5. 故障排查与常见问题实录

在实际使用中，你可能会遇到一些问题。以下是我在部署和使用过程中遇到的一些典型情况及解决方法。

5.1 安装阶段问题

问题1：执行./scripts/install.sh时，提示“Command ‘openclaw’ not found”。

原因：OpenClaw没有正确安装或没有加入到系统的PATH环境变量中。
排查：
1. 确认OpenClaw的安装路径。如果是通过包管理器安装的，尝试使用绝对路径，例如/usr/local/bin/openclaw --version。
2. 如果找到可执行文件，检查脚本中调用openclaw命令的地方。agencyteam的脚本通常直接调用openclaw，依赖系统PATH。
解决：
- 将OpenClaw的安装目录添加到你的PATH中。
- 或者，一个更直接但不那么优雅的方法是，修改agencyteam的脚本（如sync_openclaw_config.py或相关shell脚本），将openclaw命令替换为绝对路径。但这会影响项目的可维护性。

问题2：安装过程中，在“Syncing config...”步骤失败，报Python错误或JSON解析错误。

原因：你的openclaw.json配置文件可能存在格式错误，或者main.subagents.allowAgents字段的结构不符合脚本的预期。
排查：
1. 脚本会在修改前备份原配置。找到最新的备份文件（如openclaw.json.backup.xxx）。
2. 使用JSON验证工具（如python -m json.tool openclaw.json）检查当前配置文件的格式是否正确。
3. 检查main.subagents.allowAgents字段。它应该是一个字符串数组，例如[“agent1”, “agent2”]，或者是通配符[“*”]。如果它是null、一个空数组[]或格式错误，脚本可能会失败。
解决：
1. 从备份恢复配置文件：cp openclaw.json.backup.xxx openclaw.json。
2. 手动修正配置文件的JSON格式。
3. 确保main.subagents.allowAgents是一个有效的数组。如果之前没有配置过，可以手动将其设为[]（空数组）。
4. 重新运行安装脚本。

问题3：安装成功后，openclaw agents list看不到新安装的专家。

原因：网关服务可能没有成功重启，或者配置更改未生效。
排查：
1. 运行openclaw gateway status，确认服务是active状态。
2. 检查~/.openclaw/agents.list文件，看末尾是否已追加了新的agency-agents/开头的行。
3. 检查~/.openclaw/openclaw.json，查看main.subagents.allowAgents数组里是否包含了新智能体的ID。
解决：
1. 手动重启网关：openclaw gateway restart，等待片刻后再查看状态。
2. 如果配置文件正确但智能体仍不出现，可能是OpenClaw的缓存问题。尝试完全重启OpenClaw相关服务。

5.2 使用阶段问题

问题4：调用专家智能体时，主智能体报错“Subagent not allowed”或类似权限错误。

原因：该专家智能体的ID没有被包含在main.subagents.allowAgents配置列表中。
排查：检查openclaw.json中main.subagents.allowAgents的值。
- 如果是[“*”]，表示允许所有，不应该出现此问题。
- 如果是一个数组，检查其中是否包含你要调用的专家ID（例如“agency-agents/engineering-code-reviewer”）。
解决：
- 如果是agencyteam安装的专家，重新运行./scripts/install.sh（可以仅针对该专家）来重新同步配置。
- 或者，手动编辑openclaw.json，将缺失的智能体ID添加到allowAgents数组中。

问题5：专家智能体的回答质量不高或不符合预期。

原因：上游的专家提示词（System Prompt）可能不适合你的具体场景，或者OpenClaw底层的大模型能力有限。
排查：
1. 直接查看该专家智能体的系统提示词。位置在~/.openclaw/agency-agents/<agent-id>/openclaw.json中，查找system字段。
2. 思考你的任务指令是否足够清晰。给专家的指令需要具体、有上下文。
解决：
- 调整指令：尝试更详细、更结构化的任务描述。例如，不要只说“审查代码”，而要说“请以资深Python开发者的身份，审查以下代码的函数命名规范、错误处理逻辑和性能瓶颈，并按优先级列出发现的问题”。
- 自定义专家：agencyteam管理的专家文件可以被更新覆盖。如果你有更好的提示词，可以修改本地的openclaw.json文件。但请注意，下次运行update.sh时可能会被覆盖。更持久的方法是，将你修改后的版本复制到非agency-agents目录下，作为一个独立的智能体使用。
- 反馈上游：如果认为是上游提示词的通用问题，可以考虑向msitarzewski/agency-agents项目提交Issue或Pull Request。

5.3 更新与维护问题

问题6：运行./scripts/update.sh --prune-removed后，一个我还在用的专家被删除了。

原因：该专家在上游的最新版本中被移除了，而--prune-removed选项会同步这一删除操作。
解决：
- 立即恢复：如果你有文件系统备份或版本控制（如对~/.openclaw目录使用git），可以从备份中恢复该专家的目录。
- 重新安装旧版本：如果你知道该专家在哪个上游版本中存在，可以通过指定旧的AGENCYTEAM_UPSTREAM_REF来重新安装。例如：AGENCYTEAM_UPSTREAM_REF=<old_commit_hash> ./scripts/install.sh --agents “expert-name”。
- 本地备份：对于非常重要的、自定义过的专家，最好的实践是在更新前，将其整个目录复制到agency-agents目录之外的安全位置。

问题7：我想永久修改某个专家的提示词，但又不想每次更新都被覆盖。

解决：采用“派生（Fork）”模式。
1. 在~/.openclaw/agency-agents/目录下找到目标专家目录，例如engineering-code-reviewer。
2. 将其整个复制到另一个位置，例如~/.openclaw/my-experts/custom-code-reviewer。
3. 修改custom-code-reviewer/openclaw.json中的system提示词以及其他配置（如名称、ID）。
4. 修改~/.openclaw/agents.list，添加一行指向你的自定义专家路径。
5. 修改~/.openclaw/openclaw.json，将main.subagents.allowAgents数组中原来的ID替换为你的自定义ID（或添加进去）。这样，你就拥有了一个独立于agencyteam更新流程的自定义专家，可以自由修改而无需担心被覆盖。

通过以上详细的步骤解析、使用场景构建和问题排查指南，你应该能够顺利地将agencyteam-openclaw集成到你的OpenClaw工作流中，并充分利用其多专家编排能力来提升工作效率。记住，工具的价值在于如何融入你的流程，多尝试不同的专家组合和任务指令，你会发现它所能带来的协同效应远超单个通用型助手。