夜雨聆风
1. 概述
1.1 为什么需要 OpenClaw
我们在日常使用AI过程中，会感觉到构建一个Agent 系统面临着一系列现有框架难以解决的问题：
（1）多渠道消息统一处理的痛点
（2）长时运行 Agent 的挑战
（3）灵活的知识扩展需求
1.2 OpenClaw 与其他架构的区别
OpenClaw 的差异化定位体现在三个层面：
1. 基础设施层：基于 pi-mono（嵌入式 Agent 引擎），提供 ReAct 循环、LLM 调用、工具执行等底层能力
2. 平台层：在 pi-mono 之上构建路由、容错、认证管理、Skill 系统等生产级能力
3. 渠道层：统一消息抽象，让同一个 Agent 可以同时服务于多个通信平台
1.3 Agent 与 Skill 的设计理念
OpenClaw 中*同时存在两种互补的架构模式：
- Agent + Skill 架构：通过 SKILL.md 文件为 Agent 注入领域知识，就像给一个人发一本操作手册
- 主子 Agent（Subagent）架构：通过创建独立子 Agent 实现并行执行和上下文隔离，就像派出多个助手分头干活
两者不是替代关系，而是互补关系。一个 Agent 可以在读取 Skill 获得知识后，再创建多个子 Agent 并行执行任务；子 Agent 自身也可以使用 Skill。
2. Agent 核心架构
2.1 Agent 执行引擎
OpenClaw 的 Agent 执行引擎是整个系统的核心，负责从接收用户请求到返回 Agent 响应的完整流程。
2.1.1 入口与编排
就像去银行办业务：
1.两个入口，同一套流程
•你可以去柜台（命令行）
•也可以用手机银行（网关/API）
•但后面办事流程是一样的
2. 准备工作
•先查你是谁（session）
•决定派哪个柜员帮你（model）
•看你要办什么业务，准备相关材料（skills）
3. 容错保护层
•就像银行的备用柜员制度
•1号柜员忙/出问题 → 自动换2号
•2号也不行 → 换3号
•保证你的业务一定有人办
4. 真正干活
•最后由 AI 引擎来处理你的请求
一句话总结： 不管你从哪进来，都走同一条路，而且有"备胎机制"保证服务不中断。
2.1.2 ReAct 循环
Agent 的核心执行逻辑在 src/agents/pi-embedded-runner/run.ts中实现。这是一个基于 ReAct范式的循环：
1. Reasoning：LLM 分析当前上下文，决定下一步行动
2. Acting：调用工具执行具体操作
3. Observation：将工具结果反馈给 LLM
4. 重复直到任务完成或达到终止条件
外层运行循环通过 MAX_RUN_LOOP_ITERATIONS控制最大迭代次数，该值根据可用的 Auth Profile 数量动态缩放。这意味着配置了更多 API Key 的系统拥有更大的重试空间，充分利用多 Profile 轮换的优势。
2.1.3 单次执行尝试
1. 准备 workspace 目录
2. 加载 Skill entries（复用 snapshot 或重新加载）
3. 构建 System Prompt（注入 Skill 菜单、工具说明、身份信息）
4. 创建工具集（文件操作、命令执行、消息发送、子 Agent 管理等）
5. 调用 pi-coding-agent 完成一次 LLM 对话
6. 处理工具调用结果、流式输出、上下文压缩等
2.2 Agent 配置与作用域
每个 Agent 的 workspace 目录决定了它能访问哪些文件、加载哪些 Skill，形成天然的权限边界。注销、消息通知主agent等功能是 subagents steer（重定向子 Agent）和 subagents kill（终止子 Agent）操作的底层支撑。
从用户请求进入（CLI/Gateway/HTTP）、经过路由匹配、模型解析、ReAct 循环执行、工具调用、到最终响应返回的完整调用链。包含 runWithModelFallback`的回退逻辑和 runEmbeddedAttempt的内部步骤。
3. 主子 Agent（Subagent）架构
3.1 子 Agent 的设计动机
在以下场景中，单个 Agent 处理所有任务并不高效：
创建子 Agent 是主 Agent 主动决定的，不是系统自动触发。Agent（LLM）根据任务复杂度自行判断是否需要创建子 Agent。
3.2 子 Agent 创建机制
sessions_spawn工具：
子 Agent 通过 sessions_spawn工具创建（定义在 src/agents/tools/sessions-spawn-tool.ts）：
SpawnSubagentParams 参数：
注意这里没有skill或 skillFilter 参数—子 Agent 的 Skill 选择是自主的。
创建模式：
- mode: run（默认）：一次性执行，完成任务后自动结束。适合明确的单次任务。
- mode: "session：创建持久会话，可以多次交互。适合需要迭代的复杂任务。
创建流程：
spawnSubagentDirect() 的核心流程：
1. 校验参数：验证 agentId 格式、thread/mode 兼容性、sandbox 权限
2. 深度检查：检查 spawnDepth 是否超过 maxSpawnDepth，防止无限递归
3. 子 Agent 数量检查：检查 maxChildren 限制
4. 创建 child session：生成唯一的 childSessionKey
5. 注册运行：通过 registerSubagentRun 记录到注册表
6. 异步执行：调用 Gateway 的 agent 方法启动子 Agent
7. 触发 Hook：发出 subagent_spawned 事件
3.3 子 Agent 生命周期
状态追踪：
src/agents/subagent-registry.ts 维护所有子 Agent 的运行记录，核心数据结构为 subagentRuns: Map<string, SubagentRunRecord>。它提供了丰富的查询和管理 API：
- registerSubagentRun(params)：注册新的子 Agent
- listSubagentRunsForRequester(sessionKey)：列出某个父 Agent 的所有子 Agent
- countActiveRunsForSession(sessionKey)：统计活跃子 Agent 数量
- markSubagentRunTerminated(runId, reason)：标记终止
- releaseSubagentRun(childSessionKey)：释放资源
注册表还具备持久化能力：子 Agent 记录会保存到磁盘，系统重启后通过 restoreSubagentRunsFromDisk() 恢复未完成的工作。
生命周期事件：
子 Agent 的生命周期通过以下事件（`src/agents/subagent-lifecycle-events.ts`）来表示：
这些事件会被转化为结果回传给父 Agent。
推送式结果返回：
OpenClaw 采用逐个推送而非统一返回的方式处理子 Agent 结果。runSubagentAnnounceFlow()负责这个过程：
推送式返回的优势：
1. 提前处理：无需等待所有子 Agent 完成，先完成的先处理
2. 提前终止：发现答案后可以 kill 其余子 Agent，节省资源
3. 渐进式反馈：用户可以看到逐步的进度
4. 部分失败处理：某个子 Agent 失败时可以立即补救，不影响其他
5. 精细超时：每个子 Agent 独立超时，互不影响
3.4 主 Agent 对子 Agent 的管理
主 Agent 通过 subagents 工具管理子 Agent：
list：查看状态：
列出所有活跃和近期完成的子 Agent，包括运行状态、标签、模型等信息。
kill：终止执行：
- target=具体标签/ID：终止指定子 Agent
- targe tall或 target="*"：终止所有子 Agent
steer：重定向（核心容错机制，个人认为是灵魂）
当子 Agent 方向偏离或卡住时，主 Agent 可以通过 steer 重新指挥：
Steer 的执行步骤：
1. 中断当前工作：调用 abortEmbeddedPiRun() 中止子 Agent 当前执行
2. 清空队列：清除子 Agent 的待处理消息队列
3. 等待停止：确认子 Agent 已完全停止
4. 发送新指令：向子 Agent 注入新的任务描述
5. 重新开始：子 Agent 以新指令继续执行
4. 常见问题
Q1: Skill 选择需要额外调用 LLM 吗？
不需要额外调用。Skill 选择是 Agent 在正常多轮对话的第一轮中完成的——Agent 扫描 Skill 菜单，调用 `read` 工具读取 SKILL.md，这只是普通的工具调用。
Q2: Skill 能并行执行吗？
不能。Skill 是知识文档，不是执行单位。如果需要并行执行，应创建多个子 Agent，每个子 Agent 可以各自使用 Skill。
Q3: 子 Agent 的 Skill 是谁指定的？
子 Agent 自己决定。主 Agent 通过 `sessions_spawn` 只传递 `task`（任务描述），子 Agent 启动后自行加载和选择 Skill。可以通过 `agents.list[].skills` 配置限制某个 Agent 可用的 Skill 范围。
Q4: 子 Agent 之间能互相通信吗？
不能直接通信。子 Agent 的结果通过 announce 机制推送给父 Agent，由父 Agent 做信息中转。这种设计保持了架构的简洁性和可预测性。
Q5: 子 Agent 报错后怎么办？
父 Agent 会收到错误通知（`subagent-error` 事件），可以通过 `subagents` 工具进行补救：`kill` 终止后重新 spawn，或使用 `steer` 发送新指令让子 Agent 换个方向继续。
Q6: 系统支持多少层子 Agent 嵌套？
由 `maxSpawnDepth` 配置决定（默认值在 `DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH`）。达到最大深度的子 Agent 成为叶子节点，不能再创建子 Agent。
5. 结语
| 线上、线下课程安排 |
直播时间：4月18日-19日、25日-26日
AI赋能R-Meta分析核心技术：从热点挖掘到高级模型、助力高效科研与论文发表"培训班
直播时间：4月24日-27日
关于举办“OpenClaw+Vibe Coding核心实战玩法，手把手教你本地部署与云端协同，“养”出隐私安全且强大的科研辅助”培训班
直播时间：5月23日-24日
最新AI-Python机器学习、深度学习核心技术与前沿应用及Agent自动化全链路实践高级研修班
直播时间：5月16日-17日、23日-24日
一图胜千言-顶刊级科研绘图工坊暨AI支持下的Nature级数据可视化方法与实战
直播时间：5月15日-16日、22日-23日
最新AI+Python驱动的高光谱遥感全链路解析与典型案例实践高级培训班
直播时间：5月22日-23日、29日-30日
北斗高精度数据解算实战：破解城市峡谷/长基线/无网区难题，从毫米级定位到自动化交付的全流程攻坚进阶培训班
直播时间：5月21日-24日
直播时间：5月30日-31日、6月6日-7日
三维地质建模全链路实践技术——从数据清洗预处理到复杂构造建模、矿体圈定与储量估算培训班
直播时间：4月28日-30日
最新合成孔径雷达干涉测量InSAR数据处理、地形三维重建、形变信息提取、监测等实践技术应用高级培训班
直播时间：5月9日-10日、16日
第八期：融合DeepSeek、GIS 与 Python 机器学习的全流程地质灾害风险评估、易发性分析、信息化建库、灾后重建及SCI论文成果撰写高级培训班
直播时间：5月13日-14日、18日、20日-21日
从机理到实践告别“黑箱”模拟:0penGeaSys(0GS6)多物理场 THMC 全耦合建模与 Python 自动化分析高级实战营
直播时间：5月23日-24日、30日-31日
最新Hermes Agent 技能封装与科研自动化实战：以 Meta-Analysis 为例-实现从文献检索到绘图的一站式工作流培训班
直播时间：5月30日-31日
A尚研修简学践行，您随行的导师平台
NO1：平台逐步建立完整的教学方案，深度促进科研交叉技术融合，成为众多课题组及个人实践技术提升首选内容。
NO2：Ai尚研修为了更好的发展，特邀30多位专家学者作为顾问专家，为Ai尚研修平台长期发展提供了宝贵的建议及工作指导。
NO3：Ai尚研修创建云导师教学模式，最大化促进交叉学科的专业问答及交流，已经建立云导师社群300+，不仅可以学习，还为您身边带来专业的导师。
NO4：Ai尚研修建立了长期免费学术讲座：聚焦基础原理、前沿热点技术、庖丁解文、实践技术、成果推广等专题，每月4期左右，已开展完200+期，上平台都可以免费观看前期讲座。
NO5：为了深度对接用户需求，依托专家团队，针对技术咨询服务、数据处理合作、软件开发、搭建高性能计算平台等领域开展合作。
云导师【点亮科研简学践行、您的随行导师平台】
超级会员专享
END
声明： 本号旨在传播、传递、交流，对相关文章内容观点保持中立态度。涉及内容如有侵权或其他问题，请与本号联系，第一时间做出撤回。
END
Ai尚研修丨专注科研领域
技术推广，人才招聘推荐，科研活动服务
科研技术云导师，Easy Scientific Re
search
