夜雨聆风一条消息进来，接下来发生什么
前几篇我们跟着一条消息从平台到达 Gateway，经过通道适配器规范化，最终确定了它属于哪个 Session。
现在，这条消息站在了 Agent 运行时的门口。从这里开始，它要经历整个系统里工程复杂度最高的一段旅程：上下文组装、模型调用、工具执行、流式回复、上下文压缩。最终，一段有意义的回复会从另一侧出来，投递回用户所在的平台。
这段旅程由两个核心组件承担：@mariozechner/pi-agent-core（Pi Agent Core），以及包裹在它外面的 PiEmbeddedRunner。
为什么不自己实现 Agent Loop
在解释这两个组件之前，有必要先解释一个架构决策：OpenClaw 为什么把 Agent Loop 的核心逻辑委托给外部库，而不是自己实现。
Agent Loop 的基本结构并不复杂——调用模型 API，解析返回内容，如果模型要求执行工具就执行，把工具结果塞回去，再次调用模型，如此循环直到模型输出最终回复。每家公司的 AI Agent 框架都实现了这个结构。
但"实现"这个循环，和"把它做好"，是两件完全不同量级的事。边缘情况极其繁多：流式输出中断后如何恢复？工具执行超时如何处理？模型在工具调用和普通文本之间的转换格式各家不一样怎么兼容？会话历史过长时 API 报错怎么办？这些每一个都需要专门的处理逻辑，测试覆盖，以及在真实使用中反复打磨。
Pi Agent Core 由社区贡献者 Mario Zechner 开发，是一个在 OpenClaw 生产环境中经过大量真实对话验证的实现。Steinberger 做了一个务实的决定：把这个"难但通用"的部分外包出去，让 OpenClaw 专注于它独特的价值——多平台接入、记忆系统、技能体系、安全沙箱，以及让一切协同工作的胶水层。
PiEmbeddedRunner 就是那层胶水。
四层函数调用链
一条消息从进入 Agent 层到最终交给 Pi 执行，经过四层命名函数，每一层职责清晰。
第一层是 runReplyAgent()，位于 src/auto-reply/reply/agent-runner.ts。它是整个执行流程的总调度者，负责命令检测分流（/model、/think、/status 等指令在这里被拦截，不进入 Agent 执行）、模型 Failover 重试循环、typing 指示符的启停控制。
第二层是 runEmbeddedPiAgentWithFallback()，位于 src/auto-reply/reply/agent-runner-execution.ts。它实现模型降级逻辑：尝试主模型，遭遇 FailoverError 时按顺序切换备用模型，同时把 Failover 事件通知给 Gateway 广播给所有连接的客户端。
第三层是 runEmbeddedPiAgent()，位于 src/agents/pi-embedded-runner/run.ts。这是 OpenClaw 与 Pi 框架之间最主要的接口：完成模型解析、认证 Profile 轮换、上下文窗口预检、上下文压缩触发与重试。
第四层是 runEmbeddedPiAgentAttempt()，位于 src/agents/pi-embedded-runner/run/attempt.ts。单次执行尝试的完整逻辑：Session 加载、System Prompt 组装、Pi Agent Session 的创建与订阅。
第三层详解：runEmbeddedPiAgent() 做的七件事
第三层是整个运行时里逻辑最密集的地方，展开来看它在一次执行里要完成七件事。
一、模型解析。调用 resolveModel() 从 openclaw-models.json 注册表里查找目标模型的完整定义：API 类型、上下文窗口大小、支持的输入模态、计费信息。如果模型不存在，直接抛出 FailoverError(reason: "model_not_found")，触发上层的 Failover 逻辑。
二、上下文窗口预检。evaluateContextWindowGuard() 对比当前 Session 的历史 Token 估算与模型的上下文窗口大小。如果剩余窗口低于 CONTEXT_WINDOW_WARN_BELOW_TOKENS，记录警告日志；如果低于 CONTEXT_WINDOW_HARD_MIN_TOKENS，抛出 FailoverError 并阻止这次调用——此时上层会尝试切换到上下文窗口更大的备用模型。
三、认证 Profile 轮换。从 auth-profiles.json 加载当前 Agent 目录下配置的所有 API Key，通过 resolveAuthProfileOrder() 排序，选出优先级最高且未在冷却期内的 Profile。如果当前 Profile 因速率限制或认证失败被标记冷却，advanceAuthProfile() 自动切换到下一个，整个过程对上层透明。
四、Pi 扩展加载。根据当前配置决定加载哪些 Pi 扩展：如果 compactionMode 是 safeguard，加载 compaction-safeguard 扩展（多阶段压缩流水线，保留工具调用历史和文件操作摘要）；如果 contextPruning.mode 是 cache-ttl，加载 context-pruning 扩展（基于缓存 TTL 的工具结果裁剪，安静地压缩超大工具输出）。
五、单次执行尝试。调用第四层 runEmbeddedPiAgentAttempt() 进行实际执行。
六、上下文压缩。如果 runEmbeddedPiAgentAttempt() 抛出上下文溢出错误（isContextOverflowError() 或 isLikelyContextOverflowError() 检测），触发压缩流程，然后重试。注意：压缩在这里必须调用 compactEmbeddedPiSessionDirect() 而不是队列版本——因为当前执行已经持有 Session 写锁，如果调用队列版本会产生死锁。
七、Thinking 档位降级。如果模型因为不支持当前 Thinking 配置而报错，pickFallbackThinkingLevel() 会选出一个更低的档位重试，而不是直接报错给用户。
第四层详解：Session 的打开与 Pi 会话的创建
runEmbeddedPiAgentAttempt() 是实际与 Pi 框架交互的地方。它做的第一件事是打开 Session。
session-manager-cache.ts 维护了一个 SessionManager 实例的缓存，避免每次执行都重新解析 JSONL 文件。如果缓存命中直接复用，否则调用 prewarmSessionFile() 预热文件后再 SessionManager.open()。历史记录加载后，limitHistoryTurns() 根据 Session 类型裁剪历史长度：DM Session 默认保留更长的历史，群组 Session 默认更短，防止高频群聊把上下文撑满。
然后是 Pi Agent Session 的创建：
const resourceLoader = new DefaultResourceLoader({cwd: resolvedWorkspace,agentDir,settingsManager,additionalExtensionPaths,});await resourceLoader.reload();const { session } = await createAgentSession({cwd: resolvedWorkspace,agentDir,authStorage: params.authStorage,modelRegistry: params.modelRegistry,model: params.model,thinkingLevel: mapThinkingLevel(params.thinkLevel),tools: builtInTools,customTools: allCustomTools,sessionManager,settingsManager,resourceLoader,});
DefaultResourceLoader 负责从 workspace 目录加载所有上下文文件（SOUL.md、AGENTS.md、TOOLS.md 等）以及注册的 Skills。createAgentSession() 是 Pi 框架的工厂函数，把模型、工具、历史、上下文组装成一个完整的可执行会话对象。
最后，subscribeEmbeddedPiSession() 订阅 Pi 会话的事件流，把 Pi 内部的工具执行结果、流式文本、会话状态变化转换为 OpenClaw 的 Gateway 事件格式，实时推送给所有连接的客户端。
流式输出的处理：思考块与回复指令
Pi 框架以流式方式产生输出。OpenClaw 在流式输出上做了两层处理。
第一层是思考块过滤。当 Claude 的 Extended Thinking 开启时，模型输出里会夹杂 <think>...</think> 或 <thinking>...</thinking> 的内部推理内容。stripBlockTags() 函数在流式推进时识别并过滤掉这些内容，只把最终回复部分投递给用户。如果配置了 enforceFinalTag: true，则只有 <final>...</final> 标签内的内容才会被发送，实现了"模型内部推理和公开回复的明确分离"。
第二层是回复指令解析。OpenClaw 定义了一套内嵌在回复文本里的指令格式，用双方括号标记：[[media:url]]（在回复里插入媒体文件）、[[voice]]（触发语音合成）、[[reply:id]]（回复特定消息）、[[channel:名称]]（指定投递到特定通道）。这些指令在 EmbeddedBlockChunker 处理流式输出时被解析提取，转换为投递层的操作指令。
上下文压缩：四层防护，各司其职
上下文管理是长期运行 AI 助手的核心难题。OpenClaw 实现了四层独立的防护机制，从轻量到重量级依次介入。
第一层：上下文窗口预检（Context Window Guard）。执行前预检，发现剩余窗口不足时直接触发 Failover 切换更大的模型，代价极低——完全不调用模型。
第二层：工具结果裁剪（Context Pruning）。cache-ttl 模式下，对大体积工具执行结果（比如读取了一个几千行的文件）按 TTL 静默压缩，保留摘要，丢弃细节。代价低——不需要调用模型，只是截断字符串。
第三层：历史长度限制（History Limiting）。limitHistoryTurns() 对 DM 和群组 Session 各自设置历史轮次上限，超出的旧轮次直接丢弃。代价极低，但有损——丢失的历史永远找不回来。
第四层：LLM 压缩（Compaction）。上下文溢出时的最后防线，也是代价最高的一层。compactEmbeddedPiSessionDirect() 打开 Session 文件，用一套专用的 System Prompt 和工具集启动一次独立的 Agent 执行，让模型把整段对话历史浓缩成一个紧凑的摘要，然后用这个摘要替换掉原来的历史记录，再重试被中断的执行。
压缩完成后，readPostCompactionContext() 会向下一轮执行注入一个"后压缩工作区快照"——告诉模型"你的历史被压缩了，这是当前工作区的状态"，防止模型因为历史突然变短而产生困惑。
如果压缩本身也失败了（比如摘要太长把新的上下文也撑爆了，或者重试次数超限），系统会走最后的兜底路径：生成新的 sessionId，丢弃当前 JSONL，从空白状态重新开始执行。
Extended Thinking：六档深度思考
OpenClaw 暴露了 Claude 的 Extended Thinking 功能，让用户可以在对话中动态调整模型的推理深度。六个档位从 off 到 xhigh 依次对应不同的 thinkingBudget：
off：完全不启用 Thinking，最快，最省 Token minimal：极少 Thinking，适合简单问答 low：轻度 Thinking，适合有一定复杂度的问题 medium：中度 Thinking，日常复杂任务的推荐档位 high：深度 Thinking，适合需要多步推理的任务 xhigh：最深度 Thinking，适合极其复杂的分析或编程任务，Token 消耗显著增加
用户可以在配置文件里为每个 Agent 设置默认档位，也可以在对话中用 /think low、/think xhigh 随时切换。如果当前模型不支持某个档位，pickFallbackThinkingLevel() 会自动降级到最近的可用档位，不会直接报错。
Safeguard 压缩：OpenClaw 对 Pi 默认行为的替换
Pi 框架自带一个默认的压缩实现，OpenClaw 选择用自己的 compaction-safeguard 扩展把它替换掉，原因是默认实现在某些边缘情况下会丢失关键信息。
compaction-safeguard 扩展做了三件额外的事：第一，自适应 Token 预算——根据当前模型的上下文窗口大小动态调整压缩后摘要的 Token 预算，防止摘要本身也超出限制；第二，工具失败历史保留——在压缩摘要里专门保留近期工具调用失败的记录，防止模型在压缩后忘记"上次执行某个工具失败了，不要再用同样的参数重试"；第三，文件操作摘要——把近期的文件读写操作历史打包成一个结构化摘要注入压缩结果，让模型在压缩后仍然知道工作区文件的状态。
这些细节体现了 OpenClaw 在"长期可靠运行"这个目标上的工程投入程度。
小结
Agent 运行时是 OpenClaw 里代码量最大、边缘情况最多的组件。它的核心设计思路是：把通用的 Agent Loop 委托给 Pi 框架，自己只做 Pi 不做的那些事——多模型管理、认证 Profile 轮换、上下文管理的四层防护、流式输出的后处理、以及与 Gateway 事件系统的集成。
每一个看似繁琐的细节——Thinking 档位降级、Failover 死锁规避、Safeguard 扩展对默认压缩的替换——背后都是在真实部署中踩坑之后的工程修复。
下一篇，我们走进 Agent 执行的准备阶段，看 System Prompt 是如何从工作区文件、记忆片段、Skills 一层一层组装起来的。
源码参考：src/agents/pi-embedded-runner/run.ts · src/agents/pi-embedded-runner/run/attempt.ts · src/agents/pi-embedded-runner/compact.ts · src/agents/pi-extensions/compaction-safeguard.ts · src/agents/pi-extensions/context-pruning.ts · src/auto-reply/reply/agent-runner.ts基于 commit bf6ec64f 版本
