OpenClaw结构之Pi Agent

前言：

前面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	同一会话的消息串行处理，防止竞态条件	session:自动绑定
Global Lane	跨会话的全局并发控制	agents.defaults.maxConcurrent（默认4）

2.上下文组装（Context Assembly）

OpenClaw Base System Prompt + Skill System Prompts（按优先级排序）   + Boot Context（引导上下文）     + Per-Run Overrides（每次运行的覆盖配置）       + 历史消息（受 Token 预算限制）

关键约束：

强制执行模型特定的 Token 限制
预留压缩空间（compression reserve）

3.模型调用与回退（Model Fallback）

特性	说明
多模型候选链	配置多个模型（如 GPT-4 → Claude → GPT-3.5）
自动切换	当前模型失败时自动降级
溢出处理	Token 超限触发压缩重试
瞬态错误	网络/服务错误触发指数退避重试

4.生命周期管理（Lifecycle Management）

管理项	默认值	说明
运行超时	600 秒	agents.defaults.timeoutSeconds
等待超时	30 秒	agent.wait等待运行完成
取消信号	AbortSignal	支持优雅终止
状态持久化	运行结束时	保存会话状态到存储

5.事件桥接（subscribeEmbeddedPiSession）+去重机制

Agent Runner 通过 subscribeEmbeddedPiSession 将 pi-agent-core 的内部事件转换为OpenClaw的标准流：

Pi Agent 事件	转换为 OpenClaw 流
工具执行开始/结束	stream: "tool"
消息增量	stream: "assistant"
运行开始/结束/错误	stream: "lifecycle"
去重机制 directlySentBlockKeys

记录工具执行期间已发送的 block key
防止上层重复发送相同内容

6.错误恢复（Error Recovery）

错误类型	恢复动作	重试次数
Token 溢出	压缩历史消息后重试	仅 1 次
瞬态 HTTP 错误	指数退避后重试	仅 1 次
模型完全失败	切换到候选链下一个模型	直到候选耗尽

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成为个人助理的基础框架。