“

近期将连续发布《从OpenClaw源码分析小龙虾是如何工作的？》，本系列一共十篇文章。 主题为：概览与调试环境搭建->Gateway中央控制器->Session管理分析->提示词上下文分析->ReAct原理与源码分析->定时任务与心跳机制->记忆系统分析->Skill 体系分析->Channel 系统分析->自我进化机制。

第5篇：ReAct原理及源码分析

一、ReAct 范式简介

ReAct 是 Reasoning（推理） + Acting（行动） 的缩写。

传统的 LLM 只能进行”思考-回答”的单轮交互。而 ReAct 让 AI 能够：

“

思考（Thought）→ 行动（Action）→ 观察（Observation）→ 思考 → 行动 → 观察 → … → 最终答案

一个简单的 ReAct 示例

用户问题：今天北京的天气怎么样？适合出门吗？【第1轮】Thought: 我需要查询北京的天气信息Action: web_search("北京 天气 今天")Observation: 北京今天晴天，25°C，空气质量良，适合出门【第2轮】Thought: 已经获取到天气信息，可以回答用户了Action: finish("北京今天晴天，气温25°C，空气质量良，非常适合出门。")

ReAct vs 传统对话

二、OpenClaw 与 pi-mono 的关系

OpenClaw 并没有自己实现 ReAct 框架，而是直接使用了 pi-mono 框架（@mariozechner/pi-coding-agent）。

OpenClaw 无需关注底层工具执行细节，只需聚焦业务逻辑；pi-mono 则专注于标准化的 AI Agent 底层能力。

三、pi-mono 核心库介绍

3.1 设计哲学

pi-mono 是一款轻量高效的 AI Agent 运行时引擎，其核心设计理念是：

“

仅通过 Read、Write、Edit、Bash 四个工具原语，就能覆盖 90% 以上的编程场景。

核心理念：

• 不依赖向量数据库
• 以文件系统为核心上下文
• 借助命令行扩展能力
• 让 AI 能够自主编写代码、扩展自身功能

3.2 pi-mono 核心库

3.3 请求过程

四、pi-mono 基础示例

4.1 最简单的对话示例

最基本的对话例子： 导入模块 → 获取模型 → 发送请求 → 处理响应

4.2 流式请求示例

流式事件类型：

4.3 带工具的 Agent 示例

假设用户发送：”当前目录下有哪些文件？如果存在 package.json 则读取它”

=== Agent 开始 ===--- 新的一轮 ---[思考] 用户想知道当前目录下有哪些文件，并且如果存在 package.json 就读取它。       我先列出当前目录的文件，然后检查是否有 package.json。[工具调用] list_files({ directory: "." })[工具结果] .env, .env.example, .git, .gitignore, .pi, .sessions, .vscode,           agent.ts, node_modules, package-lock.json, package.json, README.md--- 轮次结束 (工具调用 1 次) ------ 新的一轮 ---[思考] 发现 package.json 存在，现在读取它。[工具调用] read_file({ path: "package.json" })[工具结果] {"name": "pi-agent","version": "1.0.0","dependencies": {"@mariozechner/pi-agent-core": "^0.65.0","@mariozechner/pi-ai": "^0.65.0"  }}--- 轮次结束 (工具调用 1 次) ------ 新的一轮 ---[回答] 当前目录下有以下文件：.env, .env.example, .git, .gitignore, .pi, .sessions,        .vscode, agent.ts, node_modules, package-lock.json, package.json, README.md        package.json 内容如下：        {"name": "pi-agent","version": "1.0.0",          ...        }--- 轮次结束 (工具调用 0 次) ---=== Agent 结束 ===

五、OpenClaw 调用 pi-mono 的完整链路

Gateway消息入口    ↓getReplyFromConfig()    ↓ (src/auto-reply/reply/get-reply.ts)runPreparedReply()    ↓ (src/auto-reply/reply/get-reply-run.ts)runReplyAgent()    ↓ (src/auto-reply/reply/agent-runner.ts)runAgentTurnWithFallback()    ↓ (src/auto-reply/reply/agent-runner-execution.ts)runWithModelFallback()    ↓ (src/agents/model-fallback.ts)    ├─→ runCliAgent() [CLI模式，跳过]    └─→ runEmbeddedPiAgent()            ↓ (src/agents/pi-embedded-runner/run.ts)        runEmbeddedAttempt()            ↓ (src/agents/pi-embedded-runner/run/attempt.ts)        ├─→ createAgentSession()  【调用 pi-mono SDK】        │       └─ from "@mariozechner/pi-coding-agent"        ├─→ subscribeEmbeddedPiSession()  【事件订阅】        │       └─ from "src/agents/pi-embedded-subscribe.ts"        └─→ activeSession.prompt()  【触发 agent 执行】                └─ 触发 pi-ai 的 streamSimple()

六、自愈机制

自愈机制是 OpenClaw 兼容故障处理中的关键一环，系统在运行中遇到故障时不是简单报错退出，而是按照从轻到重的阶梯式策略自动恢复，尽可能完成用户的请求。

runEmbeddedPiAgent()是 OpenClaw Agent 引擎的核心函数，位于 src/agents/pi-embedded-runner/run.ts。函数内部是一个 while(true) 循环，每次迭代执行一次 Agent 尝试，遇到故障时自动恢复并重试，无故障时返回结果。主要四类异常恢复：

• 上下文溢出：→ 压缩 → 截断 → 重置
• Prompt错误：→ Profile 旋转 → Thinking 降级 → 模型回退
• Assistant响应错误：→ Thinking 降级 → Profile 旋转 → 模型回退
• Thinking不支持：→ 自动降级（stream→on→off）

七、总结

1. ReAct 范式：让 AI 能够思考→行动→观察→再思考，形成闭环。
2. OpenClaw 与 pi-mono 的关系：OpenClaw 负责上层业务，pi-mono 负责底层 ReAct 执行。
3. pi-mono 核心：四个工具原语（read/write/edit/bash）覆盖 90% 场景。
4. 调用链路：Gateway → getReply → runReplyAgent → runEmbeddedPiAgent → pi-mono → LLM。
5. 自愈机制：阶梯式故障恢复，确保系统稳定运行。

下一篇讲解定时任务与心跳机制。