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 不是"发一条消息，收一条回复"，而是：模型可以多轮调用工具，每次工具结果都会追加到上下文，直到模型决定输出最终回复。
一个"帮我查天气"的请求，底层可能经历：
- 第一轮：模型决定调用浏览器工具
- 工具执行返回天气页面内容
- 第二轮：模型根据内容生成回复
- 输出最终文字，循环结束
runEmbeddedPiAgent：从调用到响应的完整流程
主入口 runEmbeddedPiAgent() 的执行顺序：
- 模型解析 → 确定使用哪个 LLM
- 认证配置文件池初始化 → 准备 API Key
- 进入重试循环 ，每次尝试执行 runEmbeddedAttempt()，包含：
- 错误处理与故障转移
系统提示：AI 人格的"源代码"
buildAgentSystemPrompt() 组装最终系统提示，包含：
- ① Bootstrap 文件内容（SOUL.md / AGENTS.md / USER.md / MEMORY.md）
- ② 记忆检索结果
- ③ 技能（Skills）
- ④ 工具说明
- ⑤ 安全约束
- ⑥ 运行时信息
- ⑦ 身份声明
修改 SOUL.md，AI 行为就改变------因为你改变了它每次推理前读到的"自我认知"。
流式输出：为什么回复是"一个字一个字"出来的
OpenClaw 使用块流式（Block Streaming）：AI 生成的原始流被按优先级分割------
段落分隔 > 行尾换行 > 句子结尾 > 空格 > 强制分割
代码块（```...）内部永远不会被分割。
上下文压缩（Compaction）：当记忆太多时
当对话上下文接近模型窗口上限时，触发自动压缩：
- 运行一次特殊 AI 调用生成对话摘要
- 压缩后重新腾出空间
- 重要内容写入 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