Pi Agent深入浅出:OpenClaw底下那层,极简四工具是怎么跑起来的

你跟终端里的 Agent 说一句：「登录页点提交没反应，帮我查。」

屏幕上开始刷文件路径、diff、命令输出。很多人以为中间是魔法。其实没有魔法。

模型在想。本地在干活。结果再塞回模型。想不动了就停。

Pi 把这件事做得特别干脆：默认只交给模型四样工具——read、write、edit、bash。OpenClaw 火的时候，很多人追小龙虾外壳；底下转工具、调模型、撑会话的那层，常常就是这套循环。

这篇不写产品简介。写清楚一件事：这四个工具，在一轮任务里到底怎么跑起来。

一先把「跑起来」画成一张图

忘掉「Agent 很聪明」这种空话。Pi 里真正转的是这个环：

你输入一句话    ↓系统提示 + 历史消息 + 四个工具的说明书  →  发给模型    ↓模型回一条助手消息，里面可能是：  · 纯文字（讲完了）  · 一个或多个 toolCall（要干活）    ↓本地运行时按名字找到工具 → 校验参数 → 真正执行    ↓把结果写成 toolResult，追加进上下文    ↓再发给模型……直到 stopReason 不是「还要调工具」

三层分工，记这张就够：

OpenClaw 之类产品，多半是在最外层再包聊天频道、权限、记忆。心脏仍是：模型提调用，本地执行，结果回灌。

模型从不直接摸你的磁盘。它只是在消息里写：我要 read，path 是某某。真正 fs.readFile / spawn 的是你机器上的 Node 进程。

这就是「四工具怎么跑」的第一句话：跑的是循环，不是某一个按钮。

二用一个假任务，把四工具串一遍

假设你说：

登录按钮点了没反应。先定位，再修，再跑相关测试。

下面是机制上常见的一串调用（真实顺序会因模型而异，但形状差不多）：

第 1 轮：摸清战场

第 2 轮：动刀

第 3 轮：收口

你会发现：没有「调试工具」「测试工具」「搜索工具」这些专名，也能走完。因为：

Pi 的极简，不是能力残缺，是：把专名压成组合。 组合靠模型编排，执行靠本地四个（加可选只读）原语。

三四个工具分别在干什么（深入，但不玄乎）

参数大致是：path，可选 offset（从第几行）、limit（读多少行）。

关键细节：

模型侧的正确用法是：先缩小范围，再精读。乱读全仓库，循环还没修好，上下文先死。

参数：path + content。

适合：新文件、模板生成、内容几乎全换。 不适合：只改三行却 write 整文件——又贵又容易无声丢改动。

参数：path、oldString、newString，可选 replaceAll。

硬规则（官方工具行为）：

为什么故意这么「笨」？因为笨才可控。模糊匹配一错，半个文件被改歪，循环后几轮全在擦屁股。

edit 逼模型先 read 出真实片段，再原样抄进 oldString。这是 Agent 改代码里最朴素、也最稳的纪律。

参数：command，可选描述。

关键细节：

所以：测试、安装、git、rg、curl，全是 bash。Pi 默认不内置「后台 bash」——长任务官方态度更偏向 tmux 这类你看得见的会话，而不是黑盒挂起。

四循环里还有三件「看不见但要命」的事

执行成功或失败，都应该变成 toolResult 消息进上下文。 文件找不到、参数校验挂、被 hook 拦住——更好的做法是 isError: true 写回去，让模型改计划，而不是进程直接炸。

UI 上你看到的「红字」，和模型下一轮看到的「错误结果」，最好是同一件事。只展示给人不回写模型，循环就瞎了。

一条助手消息里可以有多个 toolCall。只读的 read / 搜索类，常可并行；带写盘、带依赖的，要串行。

Pi 的实现味道是：能并行就并行，但 toolResult 回写仍按原始调用顺序，避免模型看到乱序上下文。

read 和 bash 都截断。因为 Agent 死法第一名永远是：工具输出把窗口灌满，后面几轮开始遗忘目标。

极简四工具能撑住 OpenClaw 级用法，有一半功劳在这：结果管道自带节流。

五会话树和压缩：循环跑久了怎么不塌

只讲四工具不够。循环一长，还有两样配套：

会话是树，不是一条直线。你可以 /tree 回到之前节点再分叉：旁支去修坏掉的工具或试另一条路，修好再回主线。旁支用摘要接回来，主上下文少掺垃圾。

上下文会压缩（compaction）。接近窗口上限时，旧消息可自动摘要。扩展还能自定义「按主题压」「换模型摘要」。这是薄 harness 能跑长任务的另一半。

再加一句交互：Agent 跑着时，Enter 是转向（steer，当前工具结束后插入，后面排队工具可跳过）；Alt+Enter 是跟进（follow-up，等这轮自然结束再问）。你不是只能干等到结束。

六装上，只为验证你看懂了循环

npm install -g --ignore-scripts @earendil-works/pi-coding-agent# 或：curl -fsSL https://pi.dev/install.sh | shcd /path/to/repopi

/login 或环境变量 API Key → 丢一句：

Summarize this repository and tell me how to run its checks.

盯屏幕：有没有 bash/read，有没有截断后的长输出，最后有没有人话收束。 那就是循环在跑。项目约定放 AGENTS.md（也认 CLAUDE.md）。

安全： 默认权限≈启动它的用户，没有细粒度弹窗。真要边界，上 Docker / 文档里的沙箱方案。

七和 Cursor / Claude Code：比的是「谁在转圈」

选型人话：

多数人该并存，不该宗教站队。

八我的判断

第一，懂 Pi，是懂所有 Coding Agent 的捷径。换皮不换骨：都是「模型发 toolCall，本地执行，结果回灌」。Pi 把皮剥到只剩四根骨头，适合当教具，也适合当底盘。

第二，四工具够不够，取决于你会不会组合。不会组合的人觉得残缺；会组合的人觉得清爽。缺的能力，用扩展 / Skill / pi install 补，或让 Pi 当场给自己写扩展再 /reload——这是它和「功能清单越来越长」的产品最大的差别。

第三，别被「极简」骗去生产机裸奔。薄 harness = 你承担更多边界责任。先侧项目、先便宜模型、先看截断和错误回写，再谈主力迁移。

参考链接