本文承接昨天的文章（我在企微里养了130个AI员工：OpenClaw+The Agency实战全记录）讲解OpenClaw内秉的多agents机制如何运作，以及如何安装并运行多agents
很多人第一次看 OpenClaw 的目录结构，都会被几个词绕住：
• workspace• agents• agentDir• sessions• subagents• sessions_spawn
接着再看到一个额外的目录：
• agency-agents
问题就变得更复杂了。
反正我一开始是晕了一阵的
这篇文章就做一件事：先把 OpenClaw 原生概念讲清楚，再解释 agency-agents 100多个agents怎么接到这套体系里。
先直观感受一下 OpenClaw 的典型目录结构：
~/.openclaw/
├── openclaw.json # 多智能体总控配置
├── workspace/ # 默认工作区（主agent）
│ ├── AGENTS.md
│ ├── SOUL.md
│ ├── TOOLS.md
│ └── memory/
│
├── agents/ # 各agent的运行态目录
│ └── <agentId>/
│ ├── agent/ # agentDir：状态、认证、模型配置
│ │ ├── auth-profiles.json
│ │ └── models.json
│ │
│ ├── sessions/ # 会话历史记录
│ │ ├── sessions.json
│ │ └── *.jsonl
│ │
│ └── subagents/ # 子任务运行登记
│ └── runs.json💡 一句话记忆：
workspace是办公桌（工作内容），agentDir是档案柜（运行状态），sessions是工作日志（历史记录），subagents是任务派工单。
一、workspace：Agent 的工作区
在 OpenClaw 里，workspace 可以理解成一个 agent 的“工作目录”或“办公桌”。
这里通常放的是 agent 运行时会读取的上下文文件，比如：
• AGENTS.md• SOUL.md• USER.md• TOOLS.md• memory/• 其他工作区级别的说明和资料
这些文件决定的不是“系统状态”，而是这个 agent 的：
• 工作方式 • 身份设定 • 语气和边界 • 可以读取到的长期/短期上下文
所以，workspace 更接近：
这个 agent 用来思考和工作的环境
而不是一个纯粹的配置缓存目录。
默认情况下
OpenClaw 的默认工作区一般是：
• ~/.openclaw/workspace
如果是多 agent，也常见这种命名方式：
• ~/.openclaw/workspace-<agentId>
但这里要注意一点：
这只是常见默认路径，不是强制命名规则。
OpenClaw 真正认的，是配置文件里给每个 agent 指定的 workspace 路径。
二、agentDir：Agent 的状态目录
如果说 workspace 是办公桌，那 agentDir 更像档案柜。
它通常对应类似这样的路径：
• ~/.openclaw/agents/<agentId>/agent
这里放的是更偏运行态、系统态的内容，比如：
• auth-profiles.json• models.json• 认证相关信息 • 模型配置 • agent 自己的状态文件
这部分和 workspace 的区别非常重要：
workspace
偏向：
• 可编辑 • 面向工作内容 • 面向上下文和人格
agentDir
偏向：
• 运行态 • 面向系统配置 • 面向认证、模型与状态
之所以分开，是因为 OpenClaw 在设计上明确区分了：
“怎么工作”
和
“怎么运行”
三、sessions：每个 Agent 的会话记录
除了 workspace 和 agentDir，每个 agent 还有自己的会话存储。
常见路径会是：
• ~/.openclaw/agents/<agentId>/sessions
这里面通常会看到：
• sessions.json• *.jsonl• 一些 lock / deleted / reset 文件
这一层记录的是：
• 这个 agent 跑过哪些会话 • 每个会话的 transcript • 哪些会话被清理、重置、归档
所以它更像：
这个 agent 的工作日志系统
这也说明一个关键点：
OpenClaw 不是“所有 agent 共用一份会话历史”，而是按 agent 分开管理。
四、subagents：子任务运行登记
再往下，就会碰到另一个容易和 agents 混淆的目录：
• subagents
这个目录不是“另一批 agent 本体”，而更像：
子代理运行记录和调度索引
例如你会看到：
• runs.json
它用来记录的，不是 agent 的人格设定，也不是 workspace，而是：
• 谁 spawn 了子任务 • 子任务运行到了哪里 • runId、状态、完成情况等
所以：
agents/<id>/sessions
存的是某个 agent 自己的会话历史
subagents/runs.json
存的是子代理任务的运行登记
两者不是一回事。
五、sessions_spawn：到底在调用什么？
理解多智能体时，最容易问的一个问题是：
sessions_spawn到底是在调用哪个目录里的 agent？
这个问题如果只从目录结构看，很容易越看越乱。更准确的答案是：
sessions_spawn调用的不是“某个目录”，而是“配置中定义好的 agent”。
也就是说，它的工作逻辑不是：
• 去磁盘上扫一圈 • 看到哪个目录像 agent 就拿来用
它真正做的是：
1. 根据 agentId找到配置里的目标 agent2. 读取这个 agent 对应的 workspace3. 读取这个 agent 对应的 agentDir4. 在这个 agent 的上下文和状态下启动一个新的子会话
所以，sessions_spawn 的本质不是“目录发现机制”，而是：
一个基于 agent 配置的会话生成机制
六、agents_list 是什么？它不是配置，是工具
要理解这一章，必须先搞清楚 OpenClaw 中”工具（Tool）”的概念。
什么是工具？
在 OpenClaw 的语境下，工具是 agent 可以调用的功能单元。你可以把它理解为 agent 的”手脚”——agent 通过调用工具来与外部世界交互。
OpenClaw 提供的工具包括但不限于：
| 文件工具 | ReadWrite、Edit | |
| 执行工具 | BashExec、Process | |
| 搜索工具 | GrepGlob | |
| 会话工具 | sessions_listsessions_send、sessions_spawn | |
| agent 查询工具 | agents_list |
工具 vs 配置：本质区别
这是最容易混淆的地方：
| 工具（Tool） | 配置（Config） | |
|---|---|---|
| 本质 | ||
| 存在形式 | ||
| 如何被使用 | ||
| 类比 |
举个例子：
• agents_list是工具 → 就像相机 App，agent 可以”打开”它来查看有哪些 agent 可用• subagents.allowAgents是配置 → 就像相机设置里的白名单，规定了 agent 能看到谁
agents_list 如何使用？
当你在 OpenClaw 界面中和 agent 对话时说：
“你能帮我列出你现在可以调用的其他 agent 吗？”
当前 agent 会主动调用 agents_list 这个工具，返回可调用的 agent 列表。
类似地：
• “帮我读取这个文件” → agent 调用 Read工具• “让 seo-specialist 来帮我分析” → agent 调用 sessions_spawn工具
常见误区
很多人以为：
只要磁盘上存在一个 agent 目录，
agents_list就应该把它列出来
但事实并非如此。agents_list 返回的不是”磁盘上有什么”，而是当前上下文中，哪些 agent 被允许通过 sessions_spawn 调用。
那它查的是哪些配置？
当 agents_list 执行时，它实际上会去检查以下几个来源：
| 全局配置 | ~/.openclaw/openclaw.json | id、workspace、agentDir 等 |
| 权限控制 | openclaw.jsonsubagents.allowAgents | |
| 运行时上下文 | agents_list，看到的列表可能不同（权限隔离） |
具体示例
假设 ~/.openclaw/openclaw.json 内容如下：
{
“agents”: [
{
“id”: “manager”,
“workspace”: “~/.openclaw/agency-agents/manager”,
“agentDir”: “~/.openclaw/agents/manager/agent”,
“subagents”: {
“allowAgents”: [“seo-specialist”, “frontend-developer”, “copywriter”]
}
},
{
“id”: “seo-specialist”,
“workspace”: “~/.openclaw/agency-agents/seo-specialist”,
“agentDir”: “~/.openclaw/agents/seo-specialist/agent”
},
{
“id”: “frontend-developer”,
“workspace”: “~/.openclaw/agency-agents/frontend-developer”,
“agentDir”: “~/.openclaw/agents/frontend-developer/agent”
},
{
“id”: “copywriter”,
“workspace”: “~/.openclaw/agency-agents/copywriter”,
“agentDir”: “~/.openclaw/agents/copywriter/agent”
},
{
“id”: “data-analyst”,
“workspace”: “~/.openclaw/agency-agents/data-analyst”,
“agentDir”: “~/.openclaw/agents/data-analyst/agent”
}
]
}注意看：
• 系统中总共配置了 5 个 agent（manager、seo-specialist、frontend-developer、copywriter、data-analyst） • 但 manager这个 agent 的subagents.allowAgents只设置了[“seo-specialist”, “frontend-developer”, “copywriter”]• 不包括 data-analyst
所以当 manager 调用 agents_list 时，它只能看到：
• seo-specialist• frontend-developer• copywriter
它看不到data-analyst，即使 data-analyst 确实在系统中存在。
💡 关键点：
subagents.allowAgents是在openclaw.json的每个 agent 配置里设置的权限白名单。
一句话总结
agents_list | 工具 | |
subagents.allowAgents | 配置 | |
openclaw.json | 配置 |
核心逻辑：agents_list 工具查询 openclaw.json 全局配置，再受 subagents.allowAgents 权限过滤，最终返回当前 agent 可调用的其他 agent 列表。
七、openclaw.json 才是多智能体的总控台
前面这些概念如果只看目录，很容易觉得零散。真正把它们串起来的是：
• ~/.openclaw/openclaw.json
在多 agent 场景下，这个配置文件会定义每个 agent 的关键属性，比如：
• id• workspace• agentDir• model • tools • bindings • subagents.allowAgents
换句话说：
目录只是承载内容的地方，配置才是 OpenClaw 真正理解 agent 的入口。
例如一个 agent 的配置，可能会长这样：
{
"id": "manager",
"workspace": "~/.openclaw/agency-agents/manager",
"agentDir": "~/.openclaw/agents/manager/agent",
"subagents": {
"allowAgents": ["seo-specialist", "frontend-developer"]
}
}或者一个没有子 agent 权限限制的简单配置：
{
"id": "seo-specialist",
"workspace": "~/.openclaw/agency-agents/seo-specialist",
"agentDir": "~/.openclaw/agents/seo-specialist/agent"
}OpenClaw 看到的是这份配置，而不是“这个目录名字听起来像不像工作区”。
八、现在再来谈 agency-agents：它到底是什么？
讲到这里，才适合引入 agency-agents。
因为这时就能把它放到一个正确的位置上：
agency-agents不是 OpenClaw 原生固定目录，而是一种外部 agent workspace 的组织方式。
这点必须强调。
OpenClaw 原生并不要求你必须有：
• ~/.openclaw/agency-agents
这个目录名不是内建保留字，也不是系统默认必须存在的层级。
它之所以在当前实例里“有效”，是因为：
• 某些 agent 的 workspace• 被配置到了 ~/.openclaw/agency-agents/<agent-id>
也就是说：
OpenClaw 原生负责的是：
• 认 workspace• 认 agentDir• 认 agentId• 认配置
agency-agents 提供的是：
• 一批预先写好的 agent workspace • 一种方便组织角色模板的目录结构
所以它更像：
被接入 OpenClaw 的 agent 模板/workspace 仓库
而不是 OpenClaw 系统本身的一层。简单讲：
agency-agents本质上是
workspace（工作区）！！！！！！
九、agency-agents 和 OpenClaw 原生概念如何对应？
如果当前机器把某个 agent 配成这样：
• workspace = ~/.openclaw/agency-agents/seo-specialist• agentDir = ~/.openclaw/agents/seo-specialist/agent
那么它们的关系就是：
~/.openclaw/agency-agents/seo-specialist对应的是这个 agent 的 workspace
~/.openclaw/agents/seo-specialist/agent对应的是这个 agent 的 agentDir
~/.openclaw/agents/seo-specialist/sessions对应的是这个 agent 的 会话历史
十、那 agency-agents 应该怎么安装？
讲到这里，安装逻辑就容易明白了。
如果 agency-agents 只是一个外部 workspace 模板来源，那么“安装它”就不应该被理解成：
把 repo clone 下来就完事
更准确的理解应该是：
把这些 workspace 接入 OpenClaw 的 agent 配置体系。
通常要经过几步：
第一步：准备 workspace
例如：
• ~/.openclaw/agency-agents/seo-specialist
这里放角色工作区内容。
第二步：准备 agentDir
例如：
• ~/.openclaw/agents/seo-specialist/agent
这里放状态目录。
第三步：注册进 OpenClaw
也就是把这个 agent 写进 openclaw.json，或者通过官方命令添加：
openclaw agents add seo-specialist
--workspace ~/.openclaw/agency-agents/seo-specialist
--agent-dir ~/.openclaw/agents/seo-specialist/agent
--non-interactive
备注：当然，你并不真的需要挨个安装，只需要把agency-agents的Github仓库喂给openclaw，让它理解之后安装即可；
这一步完成后，OpenClaw 才真正“认识”这个 agent。
所以，“安装 agency-agents”这件事，本质上不是文件复制，而是：
workspace 落地 + agentDir 准备 + agent 配置注册
十一、OpenClaw 是怎么调用这些来自 agency-agents 的 agent 的？
答案其实已经呼之欲出了：
OpenClaw 调用的不是“agency-agents 目录”，而是：
配置文件中定义的 agent
而这个 agent 的 workspace，恰好指向了 agency-agents 里的目录。
所以链路是：
1. sessions_spawn(agentId=...)2. OpenClaw 查配置 3. 找到该 agent 的 workspace4. 找到该 agent 的 agentDir5. 用这套上下文和状态启动子会话
这也是为什么：
• agency-agents本身不是内置概念• 但它依然可以很好地融入 OpenClaw 体系
因为 OpenClaw 看的是“配置结果”，不是“目录名字”。
十二、工作中到底该怎么用多 agent 协作？
把概念讲清楚之后，再谈工作方法才不会漂。
1. 单 agent 适合什么情况？
如果任务是：
• 短 • 集中 • 不需要多角色分工 • 不需要并行探索
那单 agent 就够了。
例如：
• 看一份日志 • 回答一个技术问题 • 改一段简单脚本
这类任务硬拆成多 agent，反而会增加协调成本。
2. 什么时候该用 sessions_spawn 启动其他 agent？
当一个任务天然带有“分工需求”时，通过 sessions_spawn 启动其他 agent 才真正有价值。
典型场景 A：主从协作模式
• 主 agent 负责总控和用户对话 • 通过 sessions_spawn启动seo-specialist分析关键词• 通过 sessions_spawn启动frontend-developer实现页面• 主 agent 汇总结果，统一输出
这时候的意义不是“多开几个窗口”，而是给不同任务块分配稳定角色。
典型场景 B：临时专项任务
• 已经有主任务在进行 • 但其中一个子问题可以独立解决 • 希望隔离上下文，避免污染主会话 • 或者希望并行推进，节省时间
这时候
sessions_spawn相当于把一个临时专项任务派给另一个 agent 去做，主 agent 继续自己的主线工作。
3. 主 agent 如何管理 spawn 出来的 agent？
一旦通过 sessions_spawn 启动了其他 agent，主 agent 可以通过以下工具进行管理：
sessions_list | |
sessions_history | |
sessions_send | |
sessions_spawn |
关键点：
• Sub-agent 的会话是独立的 —— 主 agent 和 sub-agent 各自有独立的 sessions目录记录• 主 agent 可以随时查看进度 —— 通过 sessions_history检查 sub-agent 的工作进展• 任务完成后结果会返回 —— sub-agent 完成后，结果会汇总给主 agent • 并发执行是支持的 —— 可以同时 spawn 多个 sub-agent 并行工作
例如，主 agent 可以这样操作：
“帮我 spawn 一个 seo-specialist 去分析关键词，同时 spawn 一个 copywriter 去写标题。等他们都完成后，汇总结果给我。”
这就是典型的主从协作管理模式。
例如：
• 主 agent 继续和用户对话 • 同时 spawn 一个 agent 去分析仓库结构 • 再 spawn 一个 agent 去整理竞品资料 • 最后统一收口
这就是很典型的 sub-agent 工作方式。
4. 一个实用原则：按“产出物”拆，不按“动作”拆
这是多智能体协作里最实用的一条经验。
不要这样拆：
• 你看文件 A • 你看文件 B • 你看文件 C
更好的拆法是：
• 你产出技术方案 • 你产出风险清单 • 你产出用户说明 • 你产出执行计划
也就是说：
让每个 sub-agent 对一个结果负责，而不是只负责一个动作。
这样最后汇总起来，质量和清晰度都会高很多。
十三、最后总结一下
如果只用一句话概括这篇文章，最重要的不是“agency-agents 是什么”，而是：
先分清 OpenClaw 原生概念，再理解外部 agent 模板是怎么被接入进去的。
更具体一点说：
• workspace是 agent 的工作区• agentDir是 agent 的状态目录• sessions是 agent 的会话记录• subagents是子任务运行登记• sessions_spawn调用的是配置中的 agent，而不是磁盘上随便哪个目录• agency-agents不是 OpenClaw 原生概念，而是当前环境里一批被接入成 workspace 的 agent 模板目录
一旦这个边界清楚了，很多原本绕口的目录结构就会突然变简单：
OpenClaw 提供的是原生多智能体框架，
agency-agents提供的是可接入这套框架的一批角色工作区。
理解了这一层，后面无论是安装 agent、扩展 agent，还是设计实际工作流，都会顺很多。
好了，赶紧挑几个合适的agents，然后用sessions_spawn来让你的主Agent指挥它们干活儿吧！
