树懒的第292篇原创
今天和一个朋友聊天，他说最近用 Pi ，很爽，非常快。我想起来最早看 OpenClaw 文档的时候，OpenClaw 用的就是 Pi。
好奇心驱使之下，我去详细调研了一下 Pi，整理如下：
先说结论：
Pi 不是一个大模型，也不只是一个命令行编程工具。它更准确的定位，是一套很轻、很透明、可以自己改造的 Agent Harness。
如果把大模型比作发动机，那么 Pi 不是另一台发动机。它更像底盘、方向盘、仪表盘和变速箱。
这也是理解 Pi 的第一把钥匙。
一、Pi 到底是什么？
很多人第一次看到 Pi，会把几个不同层次的东西混在一起。
其实 Pi 是一个开源项目家族，最核心的几层分别是：
• pi-ai：统一不同模型厂商的调用方式，负责流式输出、工具调用、认证、Token 和成本统计，也支持在同一会话中切换模型；
• pi-agent-core：真正的 Agent 循环，负责消息、状态、工具执行和事件流；
• pi-coding-agent：普通用户直接运行的终端 Agent，也就是输入 pi 后看到的那个产品；
• pi-tui：终端界面组件，负责把流式文字、工具调用和状态变化快速显示出来。
所以，别人说“我在用 Pi”，可能有三种完全不同的意思：
第一种，是把它当成一个现成的编程 Agent；第二种，是用它的 SDK 或 RPC 接口做自己的 Agent；第三种，是只拿其中一层，比如 pi-agent-core 或 pi-tui，嵌进自己的产品。
Pi 既是一个可以直接使用的工具，也是一盒可以拆开的 Agent 零件。
这正是它和很多同类产品最大的不同。
二、Pi 有什么用？
- 直接当编程 Agent 用
进入一个项目目录，启动 Pi，就可以让它读代码、写文件、修改文件、执行命令。
它默认只给模型四个工具：read、write、edit 和 bash。
别小看这四个工具。一个能读写文件、修改代码、运行命令的模型，已经可以完成绝大多数本地编程任务：理解项目、修 Bug、重构、跑测试、写脚本、生成文档，甚至调用电脑里已有的 CLI 去操作别的系统。
Pi 还支持多家模型。你可以连接 Anthropic、OpenAI、Gemini、DeepSeek、Kimi、MiniMax、OpenRouter 等服务，也可以接自定义兼容接口和本地模型。需要速度时用快模型，需要攻坚时再切强模型，不必换一套 Agent 外壳。
- 做成自己的专用 Agent
Pi 真正有意思的地方，不是它默认做了多少，而是它允许你自己决定要加什么。
• 经常重复的一套做事方法，写成 Skill；
• 经常重复的一段提示词，写成 Prompt Template；
• 需要增加新工具、命令、快捷键、权限检查、界面组件或事件钩子，写 TypeScript Extension；
• 想把这一整套能力发给别人，打成 Pi Package。
比如，你可以把 Pi 改造成代码审查 Agent、文档 Agent、运维 Agent、研究 Agent，甚至是一个只服务于自己公司内部流程的专用助手。
- 嵌进自己的产品
如果你用 Node.js 或 TypeScript，可以直接通过 SDK 创建 AgentSession；如果你的程序不是 Node.js，也可以启动 pi --mode rpc，通过标准输入输出交换 JSONL 消息。
这意味着你不必从零开始处理模型流式输出、工具循环、会话保存、上下文压缩和事件订阅。Pi 已经把最麻烦的那层骨架搭好了。
三、为什么有人会觉得 Pi 特别快？
这里一定要把“快”拆开。
Agent 的总速度，大致由四部分组成：模型生成速度、网络延迟、工具执行时间，以及 Agent 外壳自己的准备和调度开销。
Pi 能明显影响的是最后一部分。
它的默认工具少，核心很薄，没有把 MCP、多 Agent、计划模式、待办系统和复杂权限工作流全部塞进默认路径。它的终端界面又采用增量渲染，流式输出和工具状态出现得很及时。你还可以在它工作时继续输入：普通回车会排入“纠偏消息”，等当前一轮工具调用结束后送进去。
但必须说清楚：Pi 不会让同一个大模型凭空提高推理速度，他只是非常的轻，因为轻所以快。
Pi 的“快”，是因为轻，因为不做没有必要的事。
四、Pi 和 Claude Code、Codex、OpenCode 有什么区别？
Pi：给你一副骨架
Pi 的核心观念是：不替用户规定工作流。
它默认没有 MCP、没有子 Agent、没有计划模式、没有内置待办，也没有每执行一步都弹出来的权限确认。需要这些能力，可以通过 Skill、Extension 或第三方 Package 自己加。
优点是轻、透明、可改造；代价是很多事情要自己负责。
Claude Code：给你一套成熟的 Anthropic 编程工作台
Claude Code 更像一个完成度很高的成品。权限控制、MCP、计划模式、自动化接口等能力已经形成自己的工作方式，和 Claude 模型的结合也更紧。
如果你只想装好就用，不想自己设计 Agent，成品工具通常更省心。
Codex：给你一套 OpenAI 的完整 Agent 工作环境
Codex 不只是终端工具，还覆盖桌面端、IDE、云端任务、Skills、MCP、子 Agent、沙箱和审批等能力。它更强调完整工作流、安全边界和跨环境协作。
Pi 更像“我来组装自己的车”，Codex 和 claude 更像“整车、道路救援和车队系统一起交付”。
OpenCode：给你一个功能更完整的多模型开源 Agent
OpenCode 和 Pi 都支持多模型，也都可以配置和扩展。但 OpenCode 默认就提供 Build、Plan、子 Agent、细粒度权限和 MCP 等完整能力。
如果你想要开源、多模型，同时又希望常用功能开箱即用，OpenCode 更接近这个方向。Pi 则更坚持“核心越小越好”。
LangGraph、Agents SDK：给开发者搭应用的框架
这一类工具更关注工作流编排、状态、分支、追踪和生产系统集成，本身通常不是一个打开终端就能直接干活的编程 Agent。
Pi 夹在两者之间：它比纯框架更接近产品，又比完整产品更像可以拆开的工程零件。
五、Pi 和 OpenClaw 到底是什么关系？
查资料的时候发现，现在 Openclaw 已经不用 Pi 了。
OpenClaw 早期确实深度使用过 Pi 的组件，旧代码和文档里能看到 pi-agent-core、pi-coding-agent、pi-ai、pi-tui，连内部运行器都长期叫 pi-embedded-runner。至少在 2026 年 4 月的版本里，OpenClaw 仍然嵌入了 Pi 的 Agent Core。
但截至 2026 年 8 月 25 日，OpenClaw 官方最新架构已经明确写明：内置 Agent Runtime 由 OpenClaw 自己维护，不再依赖外部 Agent Framework；旧的 pi runtime 名称只是兼容别名，当前保留下来的第三方 Pi 依赖主要是 pi-tui。
所以，准确的说法应该是：
Pi 曾经是 OpenClaw 非常重要的 Agent 底座，OpenClaw 后来把这套运行时逐步内化成了自己的架构。
这件事反而能说明 Pi 的价值。一个足够小、接口清楚、可以嵌入的 Agent Harness，很适合让一个新产品快速搭起最初的 Agent 循环。等产品长大，渠道、权限、记忆、调度、模型路由和会话体系变得越来越复杂，再把底层收回自己维护，也很正常。
六、Pi 最常见的错误用法
错误一：把 Pi 当成一个更快、更聪明的模型
Pi 不是模型。回答质量首先取决于你连接的模型，其次才是上下文、工具和 Agent 设计。
换成 Pi，不等于模型自动升级。
错误二：一上来就装满插件
Pi 的优势来自默认路径很短。如果刚装好就堆上十几个 Extension、多个 MCP、复杂子 Agent 和层层钩子，最后可能又做出一套更难理解的“大平台”。
缺什么再加什么，才符合 Pi 的路子。
错误三：在敏感目录里裸奔
Pi 默认的 bash、write 和 edit 会继承启动它的用户权限。官方也明确说明，Pi 没有内置一套限制文件系统、进程、网络和凭据访问的权限系统。
这很致命！
七、Pi 正确应该怎么用？
第一步：先用最小配置跑起来
当前官方推荐的 npm 安装方式是：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
然后进入一个明确的项目目录：
cd your-project
pi
启动后用 /login 连接已有订阅，或者提前配置对应模型的 API Key。先不要装任何第三方扩展，直接用默认四个工具完成一两个真实任务。
第二步：先写好 AGENTS.md
把项目结构、常用命令、测试方法、代码规范和禁止事项写进 AGENTS.md。
不要写成长篇愿景，也不要塞入和当前项目无关的知识。它应该像一张项目操作卡，让 Agent 一进目录就知道：这里是什么，怎么验证，什么不能碰。
第三步：按照“提示词—Skill—Extension”的顺序加能力
一次性临时要求，直接在对话里说；重复使用的提示词，做成 Template；稳定的操作流程，做成 Skill；确实需要新工具、新界面或新权限逻辑，再写 Extension。
先用文字约束，文字不够时再加代码。
第四步：把安全边界放在 Pi 外面
对于重要项目和陌生代码，使用容器、虚拟机、受限用户。第三方 Pi Package 可能执行任意代码，安装前要看来源、版本和内容。
Pi 最新版本已经会在交互式启动时询问是否信任包含项目级配置或扩展的目录，但“信任项目配置”不等于“所有工具都有安全沙箱”。这两个概念不要混淆。
第五步：根据目标选择接入层
• 只想写代码：直接用 pi 终端；
• 想做自己的 Node.js Agent：使用 pi-coding-agent SDK；
• 想从其他进程控制它：使用 pi --mode rpc；
• 只想要最底层 Agent 循环：使用 pi-agent-core；
• 只想统一多家模型接口：使用 pi-ai；
• 只想做一个高响应的终端界面：研究 pi-tui。
八、Pi 适合谁，不适合谁？
Pi 很适合这几类人：
• 想研究 Agent 到底怎么运行的人；
• 想自己掌控模型、工具、提示词和界面的人；
• 想快速做一个专用 Agent 原型的人；
• 不希望被单一模型厂商锁死的人；
• 喜欢终端、愿意读配置和写一点 TypeScript 的人。
但如果你更看重开箱即用、默认安全、完整图形界面、官方云端协作，或者根本不想维护自己的 Agent 配置，那么 Claude Code、Codex、OpenCode，甚至直接使用 OpenClaw，可能更合适。
Pi 给你的不是“什么都配好了”，而是“什么都可以由你决定”，但是什么工具，什么权限，什么限制也要你来实现。
类似买成品汽车，和自己买发动机、仪表盘，手搓汽车的差别。
九、几个容易混淆的名词
• 模型：真正生成文字、代码和工具调用决策的大脑；
• Agent：能够围绕目标多轮思考并调用工具完成任务的系统；
• Agent Harness：把模型、工具、上下文、会话和执行循环接起来的运行骨架；
• Tool：Agent 可以调用的具体动作，例如读文件、执行命令；
• Skill：告诉 Agent 某类任务应该怎样完成的操作说明；
• Extension：直接扩展 Pi 程序能力的 TypeScript 模块；
• Compaction：上下文太长时，对旧对话做有损摘要，给后续任务腾空间；
• RPC：让另一个程序通过标准输入输出控制 Pi 的通信方式；
• Sandbox：限制 Agent 能访问哪些文件、命令和网络的隔离环境。
最后
调研完 Pi，我终于明白朋友为什么会觉得它“很爽、很快”，也明白 OpenClaw 最早为什么会选择它。
它没有急着替所有人定义 Agent 应该长什么样，只保留最基本的模型、工具、会话和循环，然后把剩下的决定权交给 开发者和使用者。
这种克制，带来了速度、透明和自由，也把安全、设计和维护的责任交还给了你。
Pi 真正厉害的地方就是给你一个轻快的Agent 框架。
剩下的，你自己决定。
