夜雨聆风前言：
前面2篇文章介绍了OpenClaw结构overview和Gateway，本文详细介绍Pi Agent部分。
1 Pi Agent位置
OpenClaw系统架构如下所示，会话请求经过Gateway解析后，通过agentCommand进入Agent Runtime执行层，分为2个阶段Agent Runner和Agent Loop阶段，后面我们分别介绍。
2 Agent Runner
Agent Runner是Openclaw的中央协调器（Central Orchestrator），具有如下6个功能：
1.队列调度（Lane-based Concurrency） 在Gateway中我们详细介绍了Quene Lane的机制，本身是一个机制。
参考前文： OpenClaw结构之Gateway
Agent Runner 通过双层队列系统管理并发：
| Session Lane | ||
| Global Lane |
2.上下文组装（Context Assembly）
OpenClaw Base System Prompt + Skill System Prompts（按优先级排序） + Boot Context（引导上下文） + Per-Run Overrides（每次运行的覆盖配置） + 历史消息（受 Token 预算限制）关键约束：
强制执行模型特定的 Token 限制
预留压缩空间（compression reserve）
3.模型调用与回退（Model Fallback）
| 多模型候选链 | |
| 自动切换 | |
| 溢出处理 | |
| 瞬态错误 |
4.生命周期管理（Lifecycle Management）
| 运行超时 | ||
| 等待超时 | ||
| 取消信号 | ||
| 状态持久化 |
5.事件桥接（subscribeEmbeddedPiSession）+去重机制
Agent Runner 通过 subscribeEmbeddedPiSession 将 pi-agent-core 的内部事件转换为OpenClaw的标准流：
| 去重机制 |
记录工具执行期间已发送的 block key 防止上层重复发送相同内容
6.错误恢复（Error Recovery）
3 Agent Loop
Agent loop包含6个阶段：
intake 接收 context assembly 上下文组装 model inference 模型推理 tool execution 工具执行 streaming replies 流式回复 persistence 持久化
Agent Loop在第3和第4阶段体现ReAct（Reasoning + Acting）模式，其中第3阶段model inference隐式think和reflect，第4阶段的tool execution对应Act，结果的回填对应Observe。通过大模型的推理选择是否调用工具执行，并对工具执行结果观察判断是否需要继续进入下一个阶段还是继续工具调用tool_call。
4 Pi-Agent-Core
The embedded agent runtime is built on the Pi agent core (models, tools, and prompt pipeline). Session management, discovery, tool wiring, and channel delivery are OpenClaw-owned layers on top of that core.
Agent runtime建立在Pi agent core（模型，工具和提示词） ，pi-agent-core 只提供 4 个原子工具：
read 读取文件
write 覆盖/创建文件
edit 基于字符串匹配的精确修改
bash 执行任意 Shell 命令
这种极简设计源于 Unix 哲学：模型非常擅长使用 Bash，不需要为每种操作都封装专门工具。 Agent Runner 通过 subscribeEmbeddedPiSession 将 pi-agent-core 的内部事件转换为OpenClaw的标准流。
这样设计的原因有如下3点：
1.解耦架构 OpenClaw 选择通过订阅而非直接调用的方式，是因为pi-agent-core 是独立的外部库通过事件桥接模式：
OpenClaw 不需要直接修改 pi-agent-core 的代码 双方通过标准化事件接口通信 保持了清晰的模块边界
2.事件驱动模式
这种设计体现了事件驱动架构的优势：
生产者（pi-agent-core）只负责发出事件，不关心谁在监听 桥接函数负责格式转换和路由 消费者（Gateway、渠道适配器）接收标准格式事件
3.职责分离
后记：
Pi Agent在架构设计没有遵循Plan-and-execute的模式，而是使用ReAct（Reasoning + Acting），同时使用了工程上的Quene Lane和core和agent runner解耦的设计这些，构成了OpenClaw成为个人助理的基础框架。
