OpenClaw Agent引擎内核：Pi‑Mono内核（Pi‑Agent Runtime）

OpenClaw智能体真正内核叫Pi‑Mono（简称Pi内核），使用TypeScript编写，运行在Node.js环境；整体采用外层Gateway调度器 + 内层Pi‑Mono执行内核双层架构：Gateway做上层编排，Pi‑Mono负责底层Agent循环、模型调用、工具执行、会话生命周期管理，是OpenClaw智能体的心脏。

一、内核整体分层模型

整体分为三层，解耦设计：

1. 外层：Gateway调度层（runEmbeddedPiAgent，约1200行代码）
   属于Pi的外层运行时控制器，不负责LLM推理，只做管控：会话串行执行、API‑Key动态轮换、错误分级重试、上下文窗口裁剪、Hook拦截、多租户隔离、资源限流、上下文溢出恢复。Gateway通过内部RPC调用Pi‑Mono，不走HTTP，延迟更低。
   • 动态重试算法：最大重试次数 = min(160, max(32,24 + 密钥数量×8))；配置越多API‑Key，自动分配更多重试机会，实现负载分摊；错误区分限流、鉴权失败、服务器异常、上下文超限，分类处理而不是无脑重试。
2. 内层：Pi‑Mono内核（Agent核心执行引擎）
   真正的Agent Loop实现，核心入口文件：
   • pi‑embedded‑runner.ts：主循环；
   • pi‑embedded‑subscribe.ts：流式解析；
   • pi‑embedded‑helpers.ts：上下文组装、工具解析、记忆加载。
     Pi‑Mono严格遵循ReAct范式（思考‑行动‑观察循环），内核只保留4个原子原语：read、write、edit、bash；上层所有复杂技能全部基于这4个原语扩展，保证内核极简稳定，业务能力交给上层插件化Skill系统实现。
3. 外围支撑子系统（由Pi内核驱动）
   • 会话系统：AgentSession，每个对话独立Session实例；
   • 记忆系统：SQLite + 向量混合存储；短期会话上下文 + 定期总结的长期记忆；读取SOUL.md、AGENTS.md、USER.md构建系统提示词；
   • 工具执行节点Node：分为Local‑Node本地执行、Remote‑Node远程Docker隔离执行；高危指令自动放入沙箱运行；
   • 模型适配器：统一抽象Model Provider，兼容OpenAI、Anthropic Claude、Gemini、Ollama本地模型。

二、Pi‑Mono内核完整Agent Loop执行流程（核心工作流）

每一次用户消息，Pi内核严格执行6步闭环循环：

1. 会话初始化
Gateway收到消息后创建或复用AgentSession；Pi‑Mono读取：SOUL.md（人格、价值观）、AGENTS.md（行为约束）、记忆库、历史对话上下文，拼接完整System‑Prompt。

2. 上下文压缩与窗口治理
Pi‑Mono内置上下文裁剪逻辑：当token快要溢出时自动做摘要压缩、丢弃久远对话，保留最近关键信息，防止超长上下文报错。

3. 流式调用LLM模型
通过流式SSE接收模型返回内容，Pi‑Mono实时解析返回内容，区分三类输出块：
    - 普通文本块：实时推送到Telegram、微信等消息渠道；
    - 思考块（Reasoning）：可选展示推理过程；
    - Tool‑Call工具调用指令（JSON格式）：Pi‑Mono解析工具名称和参数，交给Node执行器运行shell、文件读写、浏览器、代码运行等任务。

4. 工具执行与结果回填
工具执行完成后，Pi‑Mono把执行结果注入对话上下文，再次把更新后的全部上下文丢回给LLM，开启新一轮思考循环；循环直到模型输出最终回答，不再产生工具调用为止。

> 重点：**循环次数完全由模型决定**，内核不硬编码最大循环轮次上限；复杂任务会自动多轮思考、多次调用工具，这是OpenClaw自主完成复杂任务的关键。

5. 会话持久化
本轮对话结束后，Pi‑Mono将对话存入SQLite；后台异步任务提取重要信息写入长期记忆文件`MEMORY.md`，实现跨会话记忆。

6. 返回结果
把最终回答通过WebSocket推送回Gateway，再分发至对应消息渠道。

三、内核关键技术特性

1. 模型无关抽象层

Pi‑Mono将模型调用做抽象隔离，上层代码完全不需要关心后端是云端模型还是本地Ollama模型；同时统一处理流式解析、工具调用格式适配，适配不同模型的Function‑Call格式差异。

2. 嵌入式RPC通信模式

Gateway和Pi‑Mono使用进程内RPC通信，而非HTTP请求，大幅减少序列化开销；Gateway接管全部状态流，可以拦截、修改Agent思考过程、工具调用指令，方便做权限校验、人工审批、日志审计；Pi内核本身保持纯粹，只专注推理逻辑，业务逻辑剥离给上层Gateway，做到内核极简可维护。

3. 文档驱动内核配置

Pi内核不使用硬编码系统提示词，全部依靠*.md配置文件配置Agent行为：

• SOUL.md：人格、边界、价值观；
• AGENTS.md：工具使用规则、思考模式；
• HEARTBEAT.md：定时后台任务；
  修改文档即可改变Agent行为，不用修改内核源码，降低自定义成本。

4. 安全隔离机制

1. 内核区分可信本地节点与隔离远程节点；Shell、系统命令默认放入Docker沙箱执行；
2. Pi‑Mono会解析工具指令，高危操作（删除文件、系统级命令）触发Gateway人工确认流程；
3. 本地优先：全部会话数据、记忆文件默认保存在本机~/.openclaw目录，不会上传第三方服务器。

四、和同类Agent内核对比

1. Manus：内核是单进程整体代码，调度、循环、工具执行耦合在一起；OpenClaw采用Pi‑Mono微内核，控制平面和执行内核分离，扩展性更强；
2. AutoGPT：循环轮次写死上限；Pi‑Mono内核由模型自主决定循环次数；
3. 普通ReAct框架：大多是库（Library）；Pi‑Mono是独立运行时Runtime，自带会话管理、记忆、多渠道接入、API‑Key负载均衡、自动重试，开箱即用。

五、源码精简版架构（目录层面）

src/
├─ gateway/          # 网关进程，控制平面
└─ agents/pi‑core/
   ├─ pi‑embedded‑runner.ts      # Agent主循环
   ├─ pi‑embedded‑subscribe.ts   # 流式解析器
   ├─ session‑utils.ts           # 会话与上下文处理
   ├─ memory‑core.ts             # 记忆内核
   └─ tool‑executor.ts           # 工具调用解析

六、一句话总结内核本质

Pi‑Mono内核本质：一个Node.js实现的、文档驱动、支持自动多轮思考、内置工具调用、具备动态容错能力的ReAct智能体运行时；Gateway负责管控，Pi‑Mono负责思考与执行，二者组合构成OpenClaw完整Agent引擎。

如果你需要，我可以给你：

1. 简化版伪代码实现Pi‑Agent‑Loop；
2. 拆解Pi内核中工具调用的JSON解析逻辑。

核心结论

1. Pi‑Mono（OpenClaw内核）和OpenCode同源，但二者是完全独立产物，OpenClaw不会复用OpenCode的Agent运行时代码；OpenCode只是OpenClaw可选的模型代理服务商，并不是它底层引擎。
2. 先理清项目归属关系：
   • Pi‑Mono：Mario Zechner（libGDX创始人）开发；Pi‑Mono里面包含两套组件：
     • pi‑agent‑core：通用Agent运行时（OpenClaw采用这部分）；
     • pi‑coding‑agent：也就是后来独立拆分出来的 OpenCode（专门面向编程场景的Agent）。
   • OpenClaw：Peter Steinberger基于pi‑agent‑core SDK嵌入Pi‑Mono基础内核，然后自己独立开发Gateway网关、会话持久化、记忆系统、沙箱执行、Skill插件体系；完全抛弃pi‑coding‑agent（OpenCode）的Agent循环、权限逻辑、会话实现，OpenClaw自己重写上层调度逻辑。
   • OpenCode：脱离Pi‑Mono主仓库之后独立发展，基于Bun+TypeScript重构，变成专注代码开发的Agent；它有自己独立的Agent Loop、权限系统、子Agent调度，和OpenClaw的Pi‑Mono运行时互不依赖。

一、两层关系拆解

1）代码层面：仅共用早期底层原语定义，运行时完全分开

• 早期Pi‑Mono仓库里，无论是OpenClaw用的pi‑agent‑core，还是OpenCode前身pi‑coding‑agent，都继承Mario定下的极简理念：只有4个基础原语read/write/edit/bash；
• OpenCode拆分独立项目之后：
  • OpenCode自己实现一整套Agent Runtime，内置build、plan等专属Agent、权限规则、子Agent调度逻辑；
  • OpenClaw只取用pi‑agent‑core里基础ReAct循环、LLM适配层；会话存储、工具校验、上下文裁剪、多轮循环、记忆层全部由OpenClaw自研，不共用OpenCode代码；OpenClaw甚至不会读取OpenCode的.pi配置文件，两套环境隔离。

2）业务层面：OpenCode只是OpenClaw众多模型代理中的一个Provider

OpenClaw配置里的opencode，只是模型中转服务：

• OpenCode对外提供API网关，统一封装Claude、GPT‑4o、Kimi、GLM；OpenClaw可以选择调用OpenCode托管的模型；
• OpenCode只负责LLM推理；Agent思考循环、工具执行还是由OpenClaw内部Pi‑Mono内核完成；OpenCode不会介入OpenClaw智能体执行流程。
  简单类比：
• Pi‑Mono内核 = 发动机基础组件库；
• OpenClaw = Peter基于基础组件造了一台全能办公自动化整车；
• OpenCode = Mario拿同一套组件库单独造了一台专门写代码的专用汽车；
  两台车发动机零件源头相同，但整车控制逻辑完全独立；OpenCode还顺便对外提供加油站服务（模型API）给OpenClaw使用。

二、关键区分要点

1. 内核归属
   • OpenClaw Agent引擎：Pi‑Mono（pi‑agent‑core）+ OpenClaw自研Gateway；
   • OpenCode Agent引擎：独立自研Runtime，和Pi‑Mono后期版本代码分叉。
2. 开发者区分
   • Pi‑Mono与OpenCode：Mario Zechner；
   • OpenClaw：Peter Steinberger；两个人是奥地利开发者好友，但后期各自独立迭代项目。
3. 使用边界
   • OpenClaw可以不用OpenCode，直接对接OpenAI、Anthropic原生API；
   • OpenCode完全不能给OpenClaw提供Agent内核；二者Agent运行时互不调用。

三、一句话精简总结

OpenClaw的Pi‑Mono内核和OpenCode源自同一个早期Pi仓库，但代码早已分叉：OpenClaw只取用Pi‑Mono底层基础SDK，完全不用OpenCode的Agent内核；OpenCode对OpenClaw而言仅仅是可选的模型API服务商。

如果你愿意，我可以画出三者依赖层级图：Pi‑Mono‑core → OpenClaw；Pi‑coding‑agent → OpenCode。

核心证据分4类：GitHub仓库目录结构、NPM包划分、官方文档、代码依赖、作者本人表述；同时区分：早期同一个monorepo单仓（badlogic/pi‑mono），后期代码分叉拆分。

证据1：原始仓库 badlogic/pi‑mono 的目录结构（最硬核源码证据）

GitHub仓库：github.com/badlogic/pi‑mono，Mario Zechner（badlogic）维护的Monorepo（单仓），packages目录原生就分为两大模块：

1. packages/agent：发布为 @mariozechner/pi‑agent‑core（Pi‑Mono内核，OpenClaw所依赖的Agent运行时，包含Re‑Act循环、AgentSession、4个基础原语read/write/edit/bash、上下文处理、工具调用解析）。
2. packages/coding‑agent：发布为 @mariozechner/pi‑coding‑agent，这就是后来独立改名后的 OpenCode，面向编程场景的CLI程序、编程专属子Agent、TUI终端界面、编程扩展插件系统。
   原始仓库结构直接证明：二者最开始放在同一个Pi仓库内，共用一套底层基础代码、原语定义、pi‑ai模型适配层，只是分成两个子包：

• pi‑agent‑core：通用Agent内核（OpenClaw选用）；
• pi‑coding‑agent：代码专用Agent（后续独立成OpenCode）。

后续事件：Mario把pi‑coding‑agent拆分成独立项目OpenCode；而pi‑agent‑core继续留在pi‑mono仓库；二者之后各自独立迭代，代码分叉。OpenCode后期甚至迁移至Bun重构，脱离pi‑mono主仓库代码树。

证据2：OpenClaw仓库里的依赖与源码引用（OpenClaw侧代码证据）

1. OpenClaw仓库 github.com/steipete/openclaw：
   • package.json里直接依赖 @mariozechner/pi‑agent‑core，只引入agent内核包，没有引入pi‑coding‑agent；
   • 源码目录 src/agents/pi‑embedded‑runner.ts，直接导入pi‑agent‑core内部的createAgentSession、工具解析逻辑；Peter（OpenClaw作者）只是嵌入式调用pi‑agent‑core的运行时，自己开发Gateway、记忆系统、沙箱、多渠道适配层，完全不使用pi‑coding‑agent的代码。
2. OpenClaw的README原文致谢：

   Special thanks to Mario Zechner and pi‑mono.
   明确承认OpenClaw底层运行时来自pi‑mono仓库；OpenClaw全程没有依赖pi‑coding‑agent（OpenCode），只是共用同一个早期仓库的上游底座。

证据3：NPM包发布事实

Mario在同一个pi‑mono仓库编译输出2个NPM包：

1. @mariozechner/pi‑agent‑core：通用Agent内核，供给OpenClaw；
2. @mariozechner/pi‑coding‑agent：就是OpenCode前身；
   两个包共用仓库里packages/ai（pi‑ai模型适配层），模型调用、流式解析逻辑早期代码完全同源，后期OpenCode独立之后才重写Runtime。

证据4：作者本人和第三方权威技术文档佐证

1. Mario Zechner本人在博客、AI Engineer London演讲里说明：pi‑mono仓库分为内核SDK（agent‑core）和编码Agent（coding‑agent）；OpenClaw使用SDK，pi‑coding‑agent后续独立为OpenCode。
2. 技术文档：xiaow.dev、needhelp.icu的调研文档写明：

   Pi‑coding‑agent就是OpenCode前身，和pi‑agent‑core起源于同一个pi‑mono monorepo；OpenClaw仅使用pi‑agent‑core，后期OpenCode脱离pi‑mono独立演进，二者运行时代码分叉。

3. 社区共识：Armin Ronacher（Flask作者）的文章提到，pi‑mono的agent‑core是OpenClaw内核，coding‑agent演化成OpenCode。

理清边界（纠正容易混淆的点）

1. 同源 ≠ 后期共用代码
   • 2025‑10–2025‑12：同一个pi‑mono仓库，代码同源；
   • 2026‑01之后：pi‑coding‑agent独立拆分出来更名为OpenCode；OpenCode重写Agent Runtime，不再复用pi‑mono后续版本代码；OpenClaw继续依赖pi‑agent‑core；二者后期代码完全独立。
2. OpenClaw从来没有把OpenCode当作内核；OpenCode对于OpenClaw仅可作为可选的模型API服务商，和Agent内核无关。

极简总结证据链

同一个GitHub仓库 badlogic/pi‑mono → 分出两个子包：
pi‑agent‑core（OpenClaw Pi‑Mono内核）、pi‑coding‑agent（OpenCode前身），这就是二者源自同一个早期Pi仓库的直接证据；后期项目拆分分叉，各自独立演进。

如果你需要，我可以给你：

1. pi‑mono早期commit历史链接，查看二者还未拆分时代码；
2. OpenClaw package.json里依赖pi‑agent‑core的原文片段。