Pi Agent——OpenClaw的大脑是怎么运转的

Pi Agent 是"大脑"，但它不是凭空造出来的。

你发给 AI 一条消息，AI 是怎么决定"该不该查个天气"、“要不要调个工具”、"什么时候停下来回复你"的？这些判断，发生在 Pi Agent 里。

Pi Agent 是 OpenClaw 的推理核心——所有 AI 思考、工具执行、流式输出，都在这里进行。但它不是从零写起来的。OpenClaw 把一个独立的开源框架 pi-agent-core 嵌入进来，作为底层引擎。

在 OpenClaw 的 src/agents/ 目录里，最核心的入口函数是 runEmbeddedPiAgent()。这个函数做的第一件事，就是调用 pi-agent-core 提供的 createAgentSession()，创建一个 Agent 会话。

所以关系是这样的：

OpenClaw
  └─ 调用 pi-agent-core（第三方库）
       └─ 提供 Agent Loop 的底层实现
            └─ 负责：调模型 → 解析输出 → 执行工具 → 循环

OpenClaw 自己做的事情，是在这个底层引擎之上：

• 注入系统提示（人格、记忆、规则）
• 提供工具集（消息、浏览器、Cron 等）
• 管理会话持久化（JSONL 格式存储）
• 处理认证和模型故障转移
• 把流式输出转发给对应的消息渠道

---

为什么选择"嵌入式"而不是"子进程"

OpenClaw 直接把 pi-agent-core 当作库引入，在同一个进程里运行——这叫嵌入式运行。另一种思路是独立进程。选嵌入式的原因：

• 启动速度快
• 直接共享内存
• 原生支持流式输出零延迟
• 统一异常链
• 单个二进制部署简单

---

Agent Loop：一次 AI 推理的完整循环

理解 Pi Agent，最核心的概念是 Agent Loop（代理循环）。

现代 AI Agent 不是"发一条消息，收一条回复"，而是：模型可以多轮调用工具，每次工具结果都会追加到上下文，直到模型决定输出最终回复。

一个"帮我查天气"的请求，底层可能经历：

1. 第一轮：模型决定调用浏览器工具
2. 工具执行返回天气页面内容
3. 第二轮：模型根据内容生成回复
4. 输出最终文字，循环结束

---

runEmbeddedPiAgent：从调用到响应的完整流程

主入口 runEmbeddedPiAgent() 的执行顺序：

1. 模型解析 → 确定使用哪个 LLM
2. 认证配置文件池初始化 → 准备 API Key
3. 进入重试循环，每次尝试执行 runEmbeddedAttempt()，包含：
   • 会话准备
   • 系统提示构建（注入 SOUL.md / AGENTS.md / USER.md / MEMORY.md 及记忆检索结果）
   • 工具集组装
   • 创建 AgentSession
   • 执行 prompt 触发 Agent Loop
   • 结果处理与会话持久化
4. 错误处理与故障转移

---

系统提示：AI 人格的"源代码"

buildAgentSystemPrompt() 组装最终系统提示，包含：

• ① Bootstrap 文件内容（SOUL.md / AGENTS.md / USER.md / MEMORY.md）
• ② 记忆检索结果
• ③ 技能（Skills）
• ④ 工具说明
• ⑤ 安全约束
• ⑥ 运行时信息
• ⑦ 身份声明

修改 SOUL.md，AI 行为就改变——因为你改变了它每次推理前读到的"自我认知"。

---

流式输出：为什么回复是"一个字一个字"出来的

OpenClaw 使用块流式（Block Streaming）：AI 生成的原始流被按优先级分割——

段落分隔 > 行尾换行 > 句子结尾 > 空格 > 强制分割

代码块（```…）内部永远不会被分割。

---

上下文压缩（Compaction）：当记忆太多时

当对话上下文接近模型窗口上限时，触发自动压缩：

1. 运行一次特殊 AI 调用生成对话摘要
2. 压缩后重新腾出空间
3. 重要内容写入 MEMORY.md 成为长期记忆

---

认证故障转移：当 API Key 挂了

配置多个 API Key 时，OpenClaw 维护认证配置池：

• 失败的 Key 进入冷却
• 自动切换到下一个可用 Key
• 冷却时间按失败类型区分：速率限制（短暂）、认证失败（较长）、计费失败（长时间）

---

小结

Pi Agent 做的核心一件事：把一个通用的 AI 引擎，变成一个有记忆、有人格、能接入多渠道的个人助手。

关键设计决策是——把所有"个性化信息"以文本形式注入系统提示，而不是训练专属模型。你改一个文本文件，AI 的行为就变了。

---

本文基于 OpenClaw 2026.3.1 版本源码分析，核心文件：src/agents/pi-embedded-runner/run.ts、src/agents/pi-embedded-runner/run/attempt.ts、src/agents/system-prompt.ts