4 万 Star 的 AI Agent 底层框架 pi-mono：OpenClaw 的发动机，用 4 个工具做到了极致
2026 年，人人都想造一个自己的 AI Agent。但从零开始踩坑、从头造轮子，代价太高了。
pi-mono 是一个 TypeScript 单仓项目，专门用来构建 AI Agent 和管理 LLM 部署。OpenClaw 的核心运行时就是基于 Pi 的 SDK 构建的。这个项目已经把 Agent 底层架构打磨得非常干净，4 万 Star 不是白来的。
如果你 2026 年想造自己的 Agent，先把 pi-mono 吃透再说。
一、项目背景：为什么值得关注
pi-mono 的作者是 Mario Zechner（网名 badlogic），libGDX 游戏框架的作者。他在 AI Engineer London 大会上的演讲标题是：
"我讨厌每一个 Coding Agent，所以我自己写了一个。"
挺霸气的。而 OpenClaw 的 README 里直接写了：特别感谢 Mario Zechner 的支持以及 pi-mono。
OpenClaw 为什么选 Pi 做底层？因为 Pi 做到了一件极难的事：极致极简，却又不失强大。
开源地址：github.com/badlogic/pi-mono
二、极简哲学：4 个工具撑起一切
Pi 和其他 Coding Agent 最大的区别，在于它的设计哲学。
大多数 Agent 工具恨不得把所有功能都塞进去：MCP 支持、子 Agent、Plan 模式、权限弹窗、内置 Todo。功能列表越来越长，但你用的可能不到三分之一。
Pi 反着来。
它的核心只有 四个工具：read、write、edit、bash。系统提示词不到 1000 个 token，是所有主流 Agent 里最短的。
它刻意没有内置这些：
| 功能 | Pi 的选择 |
|---|---|
| MCP | 不内置，通过扩展按需添加 |
| 子 Agent | 不内置，保持内核纯净 |
| 权限弹窗 | 不内置，避免打断工作流 |
| Plan 模式 | 不内置，用户自行配置 |
| 内置 Todo | 不内置，交给 Skills 处理 |
| 后台 Bash | 不内置，保持简单 |
这些功能不是做不了，而是让你通过 Extensions、Skills、Packages 按需扩展。
Pi 的理念：让工具适应你的工作流，而不是让你适应工具。
Pi 给你一个干净的内核，剩下的你自己搭。不想搭也行，装别人做好的包就行。这也是为什么 OpenClaw 选了它——底层足够干净，上面才能搭出足够复杂的东西。
三、架构拆解：七个包各司其职
pi-mono 把 Agent 开发需要的每一层都拆成了独立的 npm 包：
| 包名 | 功能 | 可独立使用 |
|---|---|---|
@mariozechner/pi-ai | 统一多提供商 LLM API，对接 20+ 提供商 | ✅ 完全可独立 |
@mariozechner/pi-agent-core | Agent 运行时：工具调用循环、状态管理、上下文维护 | ✅ 只依赖 pi-ai |
@mariozechner/pi-coding-agent | 终端编程 Agent 主产品（pi 命令行），含会话管理、扩展系统、UI 渲染 | ✅ 暴露 SDK |
@mariozechner/pi-tui | 终端 UI 库，差分渲染引擎 | ✅ 可独立 |
@mariozechner/pi-web-ui | Web 端 AI 对话聊天组件 | ✅ 可独立 |
@mariozechner/pi-mom | Slack 机器人，频道消息自动委托给 Pi Agent | ✅ 可独立 |
@mariozechner/pi-pods | 管理 vLLM 在 GPU Pod 上的部署 | ✅ 可独立 |
核心亮点：每一个包都可以独立使用。
你不需要用整个 Pi——只用 pi-ai 来统一 LLM 调用也行，只用 pi-agent-core 来搭自己的 Agent 运行时也行。这就是模块化设计的威力。
pi-ai 详解：20+ LLM 统一接入
一个 API 对接 20 多个提供商，包括 OpenAI、Anthropic、Google、Azure、Kimi、MiniMax、Hugging Face 等。
你不需要关心每个提供商的 API 差异，pi-ai 帮你抹平了。
支持两种认证方式：
- API Key：标准方式
- OAuth 订阅登录：直接用 Anthropic Claude Pro/Max、OpenAI ChatGPT Plus、GitHub Copilot 的订阅来跑 Pi，不用单独买 API 额度
切换模型也极方便：Ctrl+L 呼出模型选择器，Ctrl+P 在多个模型之间快速轮换。
四、核心特性
特性 1：Sessions 树状分支
Pi 的会话用 JSONL 文件存储，每个条目有 id 和 parentId，形成树状结构。
你可以在对话中的任意历史节点分叉出去探索新方向，所有历史都保留在一个文件里。
输入 /tree 可以看到完整的对话树，支持折叠、展开、搜索、跳转。像 Git 一样管理对话历史，这个设计真的挺巧妙的。
特性 2：Extensions 扩展机制
用 TypeScript 写扩展，可以自定义：
- 工具、命令、快捷键
- UI 组件
- 替换内置工具
- 添加自定义 LLM Provider
社区里有人做了一个 Doom 扩展——在等待 Agent 回复的时候可以在终端里打 Doom，非常离谱但确实能跑。
特性 3：Skills 技能系统
遵循 Agent Skills 标准，一个 Markdown 文件就是一个技能。零代码就能扩展 Agent 的能力。
特性 4：Pi Packages 生态
把扩展、技能、提示词模板、主题打包成 npm 包，一行命令安装：
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
还有 pi.dev/packages 画廊页面展示社区包。
特性 5：四种运行模式
| 模式 | 说明 |
|---|---|
| 交互式终端 | 默认模式，pi 直接启动 |
| Print/JSON 模式 | 非交互输出，适合脚本调用 |
| RPC 模式 | stdin/stdout JSON-RPC 通信，方便进程集成 |
| SDK 模式 | 作为库嵌入你自己的应用（OpenClaw 就是这么用的） |
特性 6：上下文压缩
长会话会把上下文窗口撑爆。Pi 支持自动和手动两种压缩方式：
- 旧消息 → 总结精简
- 最近对话 → 保持原样
- 完整历史 → 仍在文件里，随时通过
/tree回溯
五、5 分钟上手
安装：
npm install -g @mariozechner/pi-coding-agent
设置 API Key：
export ANTHROPIC_API_KEY=sk-ant-...
或用订阅登录：
pi
# 输入 /login，选择提供商，浏览器完成授权
常用快捷键：
| 快捷键 | 功能 |
|---|---|
Ctrl+L | 切换模型 |
Ctrl+P | 在多个模型间轮换 |
Shift+Tab | 切换思考等级 |
Escape × 2 | 打开对话树 |
@ | 模糊搜索项目文件引用 |
! + 命令 | 直接跑 bash 并把结果发给 LLM |
安装社区包：
pi install npm:包名
写自己的扩展：
在 ~/.pi/agent/extensions/ 目录下创建一个 .ts 文件就行。
六、社区特色
Pi 的社区有几个挺有意思的地方：
贡献机制
新贡献者的 Issue 和 PR 默认自动关闭。维护者每天审核后重新打开有价值的。
通过 lgtmi 和 lgtm 两个等级晋升——拿到 lgtm 才能提交 PR。
唯一的规则：你必须理解你的代码。用 AI 写代码可以，但不理解就提交不行。
OSS Session 分享
Mario 鼓励用户把真实的编程会话数据发布到 Hugging Face，包含完整的工具调用、失败和修复过程。他认为这种真实数据比玩具基准测试有价值得多。
他自己已在 Hugging Face 上公开了 627 条以上的 pi-mono 工作会话：badlogicgames/pi-mono
七、pi-mono vs Claude Code
| 维度 | pi-mono (Pi) | Claude Code |
|---|---|---|
| 设计哲学 | 极简内核 + 按需扩展 | 功能齐全的终端 Agent |
| 定制性 | 极高，可替换任何组件 | 有限，预设配置 |
| 透明度 | 系统提示词 <1000 token，全部可见 | 相对黑箱 |
| 多模型 | 20+ 提供商统一接入 | 主要依赖 Anthropic |
| 生态 | npm 包 + 扩展 + Skills | 依赖 Anthropic 生态 |
| 集成能力 | 4 种运行模式，可作为库嵌入 | 主要是 CLI |
和 Claude Code 比，Pi 更极简更可定制。 它是终端原生工具，不是 IDE 插件。更轻量，也更透明。
如果你是 Agent 开发者，想基于成熟的底层搭自己的产品，Pi 的 SDK 和 pi-ai 包就是为你准备的。OpenClaw 已经证明这条路走得通。
最简洁的底层，支撑起了最复杂的应用。
站在巨人的肩膀上，比从地上爬起来快多了。