Pi 不是大模型，而是一套可拆装、可嵌入的 Agent Harness

朋友最近把日常编程切到 Pi 上，反馈是“快”。这跟早期 OpenClaw 文档里看到的迹象对得上：OpenClaw 最早的运行时用的就是 Pi。出于这个原因，我把 Pi 完整调研了一遍。

先说结论：Pi 不是一个模型，也不是普通意义上的命令行 Agent 产品。它的准确定位是一套很轻、透明、可以自行改造的 Agent Harness。

把大模型比作发动机，Pi 不是另一台发动机，而是底盘、方向盘、仪表盘和变速箱。理解这一点，是后续所有使用方式的前提。

Pi 项目家族的四层结构

Pi 是一个开源项目家族，核心分层如下：

• pi-ai：统一各家模型厂商的调用方式，负责流式输出、工具调用、认证、Token 与成本统计，支持在同一会话中切换模型；
• pi-agent-core：真正的 Agent 循环，负责消息、状态、工具执行和事件流；
• pi-coding-agent：普通用户直接运行的终端 Agent，也就是输入 pi 后看到的那个产品；
• pi-tui：终端界面组件，负责流式文字、工具调用、状态变化的快速渲染。

因此“我在用 Pi”可能指三件完全不同的事：

1. 把 Pi 直接当现成的编程 Agent 用；
2. 用它的 SDK 或 RPC 接口构建自己的 Agent；
3. 只拿其中某一层（比如 pi-agent-core 或 pi-tui）嵌进自己的产品。

Pi 既是一个可以立刻使用的工具，也是一盒可以拆开的 Agent 零件。

Pi 的三种用法：直接跑、改造成专用 Agent、嵌进产品

1. 直接当编程 Agent 用

进入项目目录，启动 Pi，让它读代码、写文件、改文件、执行命令。

它默认只给模型四个工具：read、write、edit、bash。

这四个工具已经覆盖绝大多数本地编程任务：理解项目、修 Bug、重构、跑测试、写脚本、生成文档，以及调用机器上已有的 CLI 去操作外部系统。

Pi 支持多家模型：可以连 Anthropic、OpenAI、Gemini、DeepSeek、Kimi、MiniMax、OpenRouter，也可以接自定义兼容接口和本地模型。需要速度时切快模型，攻坚时切强模型，不需要换掉整套 Agent 壳。

2. 做成自己的专用 Agent

Pi 真正有意思的不是默认做了多少，而是它允许你决定加什么：

• 经常重复的一套做事方法写成 Skill；
• 经常重复的提示词写成 Prompt Template；
• 需要新增工具、命令、快捷键、权限检查、界面组件或事件钩子，写 TypeScript Extension；
• 想把这整套能力分发给别人，打成 Pi Package。

例如把 Pi 改造成代码审查 Agent、文档 Agent、运维 Agent、研究 Agent，或者只服务公司内部流程的专用助手。

3. 嵌进自己的产品

Node.js / TypeScript 环境可以直接用 SDK 创建 AgentSession。非 Node.js 程序可以启动 pi --mode rpc，通过 stdin/stdout 交换 JSONL 消息。

模型流式输出、工具循环、会话保存、上下文压缩和事件订阅这类基础骨架，不需要从零处理。

Pi 的“快”来自轻，它只优化最后一段

单轮 Agent 响应总耗时大致由四段组成：模型生成速度、网络延迟、工具执行时间、Agent 外壳的准备与调度开销。Pi 能明显影响的只有最后一段。

它的默认路径很短：工具少、核心薄，没有把 MCP、多 Agent、计划模式、待办系统和复杂权限工作流塞进默认流程。终端界面用增量渲染，流式输出和工具状态出现得及时。它甚至允许你在 Agent 工作期间继续输入：普通回车会排入“纠偏消息”，等当前这轮工具调用结束后再送进去。

需要说清楚的是：Pi 不会让同一个模型凭空提高推理速度，它只是因为轻，所以快。 不做不必要的事，是“快”的主要来源。

Pi 与 Claude Code、Codex、OpenCode、“框架类”工具的差异

• Pi：给你一副骨架，不替你规定工作流。 默认没有 MCP、子 Agent、计划模式、内置待办、逐步权限确认。这些能力都可以通过 Skill、Extension 或第三方 Package 自己加。代价是很多事要自己负责。

• Claude Code：更接近完成度很高的成品。 权限控制、MCP、计划模式、自动化接口已经形成自己的工作方式，和 Claude 模型结合紧密。只追求装好就用，不想自己设计 Agent，成品工具通常更省心。

• Codex：一套完整的 Agent 工作环境。 不只是终端，还覆盖桌面端、IDE、云端任务、Skills、MCP、子 Agent、沙箱和审批。它强调完整工作流、安全边界、跨环境协作。相对而言，Pi 更像“自己组装车”，Codex 更像“整车、道路救援和车队一起交付”。

• OpenCode：功能更完整的多模型开源 Agent。 和 Pi 一样支持多模型、可配置可扩展，但 OpenCode 默认就提供 Build、Plan、子 Agent、细粒度权限、MCP 等能力。想要开源、多模型且常用功能开箱即用，OpenCode 更接近这个方向；Pi 则坚持“核心越小越好”。

• LangGraph、Agents SDK：给开发者搭应用的框架。 这类工具关注工作流编排、状态、分支、追踪和生产系统集成，本身通常不是一个打开终端就能直接干活的编程 Agent。Pi 夹在中间：比纯框架更接近产品，又比完整产品更接近可拆开的工程零件。

Pi 与 OpenClaw 的关系：底座被逐步内化

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 没有替所有人定义 Agent 应该长什么样。它只保留最基本的模型、工具、会话和循环，把剩下的决定权交给开发者。速度、透明和自由来源于这种克制，安全、设计和维护的责任，也一并交还给了你。