AI news

OpenClaw 背后核心框架 Pi:好的 Coding Agent 应该让用户来决定需要什么

By Founder Park3 viewsSource: Founder Park
OpenClaw 背后核心框架 Pi:好的 Coding Agent 应该让用户来决定需要什么

OpenClaw,是当下最火的开源个人 AI 助手。很多人不知道的是,OpenClaw 背后,核心是一个极简框架 Pi-coding-agent。

The full text has not been translated yet. The Chinese original is shown below.

OpenClaw,是当下最火的开源个人 AI 助手。很多人不知道的是,OpenClaw 背后,核心是一个极简框架 Pi-coding-agent。

在 OpenClaw 的系统架构中,Pi agent 是 Gateway 控制层的核心子系统,控制了所有 agent 的推理和工具调用。

和 Claude Code、Cursor、Codex 不同的是,Pi 最大的特点是「做减法」:系统提示词和工具定义加起来不到 1000 tokens,核心只有 read、write、edit、bash 四个工具,没有内置 plan mode,没有 to-do 系统,没有 MCP 支持,没有权限弹窗,甚至没有绑定任何特定模型。

但就是这样一个「什么都没有」的框架,在 Terminal Bench 2.0 上与 Codex、Cursor、Windsurf 一同排进了前五。在 GitHub 上,Pi 积累了超过 24000 stars 和 148 位贡献者。

Pi 的作者是奥地利的开发者 Mario Zechner,有着二十多年的开源经验。Mario 此前曾开发了 Java 跨平台游戏开发框架 libGDX,在 GitHub 上拥有 2 万标星。

Mario 认为,好的 coding agent 不应该预设你需要什么,而是应该让你自己决定需要什么。

在最近的一场 AMA 的直播活动上,Mario 和 Pi 框架的三位深度用户,Sentry 工程高级总监 Daniel、Pi 核心贡献者 Armen、以及 Modem 创始人 Ben,聊了聊他对于 Pi 的极简设计思路,以及对当下 Coding Agent 的一些思考。

以下为活动中的部分精华内容。

01

在经过大量的 RL 后,

大模型天然就知道 coding harness 是什么

主持人:市面上已经有像 Claude Code 这样成熟的产品了,最初是怎么想到要自己写一个 Pi 的?

Mario:说实话,因为我受够了 Claude Code(笑)。我很喜欢 Claude Code,它是定义了 Coding 的产品,团队也很棒。但输出的东西老是坏,我说的不是 bug,而是我自己的工作流被破坏了,因为 harness 变了,模型的行为就跟着变了。

作为工程师,我需要更可靠的工具。当然,在 2026 年说这话有点讽刺,因为 LLM 本身就不可靠,但至少我个人能让它确定性的部分,我希望它是确定性的,包括工具、系统提示词、以及背后被注入的所有东西。

如果你去看 Claude Code 或者 OpenAI 的 Codex,它们会在你的上下文里偷偷塞进很多东西,而且不会在 UI 上展示给你。这些东西会以最微妙的方式破坏你的工作流。它们的发布节奏是每天一次甚至一天多次,你可以 9 点开始工作、工作流跑得好好的,10 点就坏了,下午 3 点又变成完全不同的行为,模型没变,变的是 harness。在这样的情况下,我没法工作。

主持人:Pi 的极简设计,最初是受到了什么启发?

Mario:来自一个观察。在写 Pi 之前,我去看了 Terminal Bench 的排行榜,上面有一个叫 Terminus 的 harness,非常神奇,它只给 LLM 一个工具,跟 tmux session 交互。LLM 必须发送单独的按键,读取 tmux 返回的 ANSI 序列来完成任务。就这么一个工具,它几乎永远排在前三,而且经常是第一名。

这给了我一个划痕关键的直觉:模型现在经过了大量的强化学习训练,它们天然就知道 coding harness 是什么,不需要在上面堆加太多东西。Pi 就是这个理念的实现:一个极简但可扩展的 harness。

Mario 在开发博客中写道:

过去几个月里,Claude Code 变成了一艘宇宙飞船,其中 80% 的功能我完全用不上。系统提示词和工具定义在每次发布时都会变,这破坏了我的工作流、改变了模型行为。我恨透了这一点。另外,它还会闪屏。

02

系统提示词不到 1000 tokens,

Pi 坚持「极简」设计

Pi 最大的特点是,整套系统提示词加工具定义加起来不到 1000 tokens。作为对比,Claude Code 的系统提示词超过 10000 tokens,OpenCode 的模型专用提示词也是类似这种的量级。

这么短的提示词,Pi 是怎么做的?

Mario 在一篇博客文章中,分享了他的设计理念。

Mario 提到,应该把 LLM 当作「用自然语言编程的通用计算机」,prompt 不是对话,而是代码,有输入、状态、输出和控制流。状态应该序列化到磁盘上的 JSON 和 Markdown 文件里,这样你可以从任意一个断点重启、用全新的上下文继续,从根本上绕过上下文衰减问题。Mario 用这套方法把一个原本需要 2-3 周的游戏引擎跨语言移植任务压缩到了 2-3 天。

同样,Mario 在 Pi 的设计中,也明确了几个主动选择「不做」的功能:

不支持 MCP。主流 MCP server 会把大量工具定义一次性灌入上下文。Playwright MCP 有 21 个工具、消耗 13700 tokens;Chrome DevTools MCP 有 26 个工具、消耗 18000 tokens,还没开始干活,上下文窗口就少了 7%-9%,而且这些工具在当次 session 中大多数你根本用不到。

Mario 给出的替代方案是,写 CLI 工具配 README 文件。agent 需要某个工具时才读对应的 README,按需付出 token 成本,然后用 bash 调用。他用这种方式搭建了一套浏览器自动化工具集,总共只消耗 225 tokens,是 Playwright MCP 的 1/60。

不内置 plan mode。直接告诉 agent "我们先一起想清楚这个问题,不要改文件也不要执行命令"就够了。如果需要跨 session 的规划,写到 PLAN.md 里,agent 可以读、可以改、可以引用,而且这个文件可以随代码一起版本化。

Mario 特别强调了可观测性:在 Claude Code 的 plan mode 里,它会在背后生成子 agent,你完全看不到这个子 agent 做了什么,不知道它读了哪些文件、漏掉了哪些。在 Pi 里,所有的探索过程都在你面前,你可以看到 agent 读了什么、遗漏了什么。

不内置 to-do 系统。Mario 的经验是,to-do 列表通常让模型更困惑而不是更高效,增加了模型需要追踪和更新的状态,会引入更多出错的机会。

不做后台 bash。后台进程管理会引入大量复杂性,进程追踪、输出缓冲、退出清理、向运行中的进程发送输入。Claude Code 有后台 bash 功能,但它的可观测性很差,而且在早期版本中,上下文压缩后 agent 会忘掉所有后台进程并且没有工具去查询它们。

不内置 SubAgent。在这一点上,Mario 的态度最坚决。Claude Code 执行复杂任务时经常在背后生成 SubAgent,完全看不到子 agent 的对话过程,属于「黑箱里的黑箱」。

如果需要 Pi 生成自己,直接用 bash 启动一个新的 Pi 实例就行了,甚至可以放在 tmux 里跑,获得完全的可观测性。

Mario 在博客中写道:

在 session 中途用 SubAgent做上下文收集,说明你没有提前规划好。如果你需要收集上下文,在一个独立的 session 里先做完,产出一个 artifact,然后在新 session 里用这个 artifact 给 agent 提供干净的上下文。

03

在 Pi 框架下,

大家的使用工作流都不一样

主持人:Daniel,你作为大厂的工程总监,个人使用 AI 编程工具的演进路径是什么样的?

Daniel:我经历了很长一段时间的变化。2024 年夏天,ChatGPT 已经好到可以一次就能帮你搞定一个脚本了。以前写脚本要花几小时查文档和 API,现在几分钟就完事,但体验很原始,打开网页、复制粘贴、本地创建文件,太笨重了。

真正的 magic moment 是 2025 年 6 月,Cursor 实现了 agentic loop。我第一次对 agent 编程上瘾了,一个周末、两个晚上,从零搭了一个包含前后端和用户登录的完整 Web 应用,放在以前至少要一到两周。

然后就是 2025 年底,Opus 4.5 出来了,我彻底迷上了 Claude Code。之前 agent 大概 50% 的时候能用,Opus 4.5 让它变成了 80% 能用。

主持人:最后为什么你还是弃用 Claude Code 了?

Daniel:大概 2026 年 1 月,我发现了问题。Claude Code 像一辆超级舒适的车,你坐进去,它就能把你送到目的地。而且它非常乐观,会告诉你"我们能搞定的"。但有时候它会骗你说,「已经 production ready 了」,结果你一打开就崩溃了。

每次开一个新的 session 时,我都要重复同样的指令,但同样的错误又来了,hooks 机制刚推出就有 bug。Claude Code 本身不稳定,有时候直接崩溃把你踢出去,所以要从断点恢复几乎是不可能的。

我被弹回了两次,前两次装完 Pi,感觉回到了「石器时代」,什么都没有。但第三次我换了策略:不用 Pi 去做一个功能,而是用 Pi 来构建我自己的 agent。这是真正的 Aha moment。

主持人:面对 Pi 这么极简的框架,你们三位的使用方式差异很大。分别讲讲各自日常的工作流。

Daniel:我的工作流是这样的:首先用我调整过的 brainstorming skill 做规划,它要求模型给出三种方案:一个激进的、一个务实的、一个豪华的,然后我跟模型讨论,最终确定方案。这个过程产出一个 markdown 计划文件和一系列 to-dos。

然后进入实施阶段。如果是已有代码库,先启动一个 scoutSubAgent 去探索需要改动的文件,把结果传给 worker agents。Worker agents 只用 Sonnet 4.6,因为任务已经足够明确,不需要 Opus。更快也更便宜。实施完成后,用 Codex reviewerSubAgent 做代码审查。

最有意思的部分是迭代修复。大功能实施完之后,我通常还剩 40% 到 60% 的上下文窗口,而且是完美的热上下文。我不需要重新解释我们在做什么、用了什么技术、为什么做了某些取舍。直接使用应用、找到问题、让 agent 修复、然后 rewind 回实施完成的节点、修下一个问题,如此循环直到打磨完成。

Armen:我更关注怎么让 agent 更高效。比如我完全替换了 Pi 的内置 edit tool,换成支持 patch-based 多文件编辑的版本,灵感来自 Codex 的 apply patch。

另一个我重度使用的是 answer 扩展。Claude Code 的 plan mode 会给上下文注入一个"提问"工具,即使你不在 plan mode 里它也一直存在,有时候会在不需要的时候蹦出来。我写了一个 answer 扩展替代它,提取模型提出的所有问题,重新渲染成 UI,逐个回答后提交,完全不消耗上下文。

我还让 agent 在验证改动时自动截图。Pi 是少数能把截图读进 LLM 并且漂亮显示的编程 agent。即使几天后加载旧 session,我仍然能看到 agent 当时截的每一张图。

Mario:我个人只有两个扩展,而且是特定项目的。我只要我的极简体验:打个招呼、开始干活、别出错。我给你们造了一台 meta slop machine(元 slop 机器),这样你们可以尽情发挥。而我自己住在我非常斯巴达式的世界里。

04

让多个SubAgent并行开发的模式,

行不通

Mario 此前在博客中,提到:

让多个子 agent 并行开发不同功能,在我看来是一种反模式,不会有好结果,除非你不在乎代码库变成一堆垃圾。

在 session 中途用子 agent 做上下文收集,说明你没有提前规划好。如果你需要收集上下文,在一个独立的 session 里先做完,产出一个 artifact,然后在新 session 里用这个 artifact 给 agent 提供干净的上下文。这个 artifact 对下一个功能可能也有用,而且你能获得完全的可观测性和可操控性,这在上下文收集阶段至关重要。

去看看 Pi 的 issue tracker 和 pull requests 吧。很多都被关闭或者要求修改了,因为那些 agent 无法完全理解项目需要什么。这不是贡献者的错,即使是不完整的 PR 也能帮我更快地推进。但这说明我们对 agent 的信任还是太多了。

主持人:在 SubAgent 上,大家的分歧似乎很大。

Mario:我从来没发现 SubAgent、编排、swarm 这些东西对我有效。但这可能也因为我仍然会阅读 agent 产出的大部分代码。我不想要 10 个 agent 同时干活,然后一天结束时 review 2 万行代码,这对人类大脑来说不可扩展,而且那 2 万行代码大概率质量不行。

我不追求每天创建更多功能,我追求的是每天能做更多决策,关于产品需要什么、不需要什么。

我的替代方案是用 /tree 命令。让 agent 自由探索代码库,然后做一个摘要,回到起点只带上摘要继续工作。这是我的穷人版 SubAgent。

Armen:我的看法是,你必须先把串行流程跑通了,才能考虑并行化。我到现在还没有找到一种方法可以自动化「探索」这一步。如果我自己还得在 loop 里,并行化对我帮助不大。

Mario:有一个不错的反例。Shopify 的 Tobi 做了一个 Pi 扩展,给你一个本地指标,agent 们在解空间里并行探索不同的优化方案。对这种「把东西往墙上扔、看哪个粘住了」的探索型任务,SubAgent 确实很强大。但对于真正的功能构建,我还是要在 loop 里,我还是要做最后拍板的人。

Armen:我昨晚刚用 auto-research 跑了一下我自己的模板引擎。即便是这种场景,也只能串行跑,并行的话会同时引入太多修改,你得退回大部分,结果就是一堆 merge conflicts。不过效果确实不错,引擎快了大约 20%。

05

大部分 Coding Agent 的权限系统,

都是「安全剧场」

主持人:在安全问题上,Pi 的设置是,完全没有权限系统。为什么这么设计?

Mario:这被 Simon Willison 称为「trifecta」:如果你给 agent 执行命令的能力、读取网络内容的能力、以及读取本地文件的能力,你就完蛋了。目前,其实没有好的解决方案。

至于那些权限弹窗?可爱,但不解决问题。它导致的是 permission fatigue,用户被 agent 不断打断,最后就会一路 yes yes yes,然后干脆"跳过所有权限"。

Mario 在此前的博客中写道:

看看其他编程 agent 的安全措施,大部分都是安全剧场(security theater)。只要你的 agent 能写代码和执行代码,就已经 game over 了。唯一能防止数据泄露的方法是切断执行环境的所有网络连接,但这会让 agent 基本没法用。域名白名单也能通过其他手段绕过。

Simon Willison 写了大量关于这个问题的文章。他提出的 "dual LLM" 模式试图解决 confused deputy attack 和数据窃取,但他自己也承认"这个方案相当糟糕",而且引入了巨大的实现复杂度。核心问题不变:如果一个 LLM 能读取私有数据又能发起网络请求,你就是在玩打地鼠游戏。

既然我们解决不了这个"三体难题"(读数据 + 执行代码 + 网络访问),Pi 就直接投降了。反正所有人最终都会切换到 YOLO 模式来提高生产效率,那为什么不把它作为默认的、唯一的选项?

Armen:权限系统还有另一个问题。即使你拒绝了大部分权限,只给 agent 跑一个脚本的权限,它会通过这一个脚本做所有事情。你可以自己试:给 Claude Code 或 Codex,只允许它运行 checkout 里的一个脚本文件,它会开始编辑这个文件来实现各种改动。非常聪明,但也说明了权限系统形同虚设。

Mario:我个人的做法是:在宿主机上有需要保护的东西,就把 Pi 放进 Docker 容器,只挂载它需要的数据。其他时候就全开。

06

Coding Agent不需要额外的长期记忆

主持人:你们觉得 Coding Agent 需要额外维护一套记忆系统吗?你们怎么看 agent 的长期记忆?

Mario:我认为目前不需要,至少对编程任务来说不需要。代码库就是 source of truth,我不需要在代码库之上维护一层额外的信息。

我认为 Claude Code 最伟大的发明之一是搜索,不是去索引、向量化、BM25 检索你的代码库,而是让 agent 每次从零开始,探索代码库的当前状态,然后再动手。这以前做得不好,现在做得非常好,尤其是 Codex,它在收集上下文方面真的很强。

传统的做法是什么?写文档,然后文档一周就过时了,没人读。代码才是真相。让 agent 探索代码库的当前状态,是编程任务目前最好的做法。对于其他场景,比如 OpenClaw 那种需要记住你家庭成员信息的个人助手,当然可以用记忆系统。但写代码不需要。

Daniel:我试过一种方法:session 快超出上下文窗口了就做一个摘要,在新 session 里从摘要继续。但我发现没什么用,只是往上下文里塞了更多东西。最后我就用本地的 agents.md,想让 agent 下次记住什么,写进去就行,够用了。

Armen:我们做了一些实验,把最近的 Git 变更推进上下文,帮 agent 从上次断点继续。结果好坏参半。目前没被说服。

07

你的 AI「变笨了」,

并不是错觉

主持人:很多人提到,经常觉得自己的工具「变笨了」,AI 工具在悄悄「gaslight」开发者,你们怎么看?

Mario:如果你经常觉得你的工具「变笨了」,这并不是错觉。

2025 年 8 月,我开发了一个叫 cchistory 的工具,专门用来追踪 Claude Code 每个版本的系统提示词和工具定义变更。

在 cchistory 的记录下,发现了大量的「静默调整」:

  • 早期版本会把完整的项目目录树注入系统提示词,后来被删掉了,因为它严重污染上下文;

  • 一条要求 Claude 清理测试/调试文件的指令被移除,因为 Claude 过于激进地删除了合法文件;

  • Bash 命令解释的要求也被去掉了,可能是为了降低服务器负载;

  • 安全相关的措辞从笼统的"拒绝创建恶意代码"演变为更细致的分类;

  • Grep 工具经历了重大重构,强制要求使用内置 Grep 而非 bash grep;

虽然每一条变更都合情合理,但问题是:用户对此完全不知情,而每一条都可能改变模型在你 session 中的行为。

Armen:我们现在做的这个 vibe-based engineering 非常疯狂。以前我们行业有一个很重要的原则:不随便改 API、保持向后兼容。现在因为所有接口都是自然语言,MCP server 没有稳定接口,系统提示词没有稳定接口,各种 agent harness 上面还有随机的 A/B 测试。你日常使用的工具,每一层都在不断被 gaslight。

我甚至觉得,虽然可能完全是我的错觉,当美国那边醒了之后,我的 agent 表现就会变差。但我也不知道是不是真的,因为我对正在发生的事情几乎没有任何能见度。

Mario:这也是我造 Pi 的动机之一。我不想要一个别人可以随时在背后改变的工具。我想要确定性的工具、确定性的系统提示词、确定性的行为。如果行为不对,我自己来改,至少我知道改了什么。

Claude Code 或 Codex 在后台推了多少东西到你的上下文里,你是看不到的。而所有这些,都在以最微妙的方式影响着你的工作。

主持人:现在满世界都是能自动写代码、提 PR 的 AI,这给你的开源社区维护带来了什么挑战?

Mario:大量完全由 AI 生成、没有人工监督的 issue 和 PR 涌入我的仓库。一个标题看起来合理的 PR,点进去一看,天哪,PR 描述是一本书的长度,改了 30 到 100 个文件。有时候是好的,有时候是垃圾,但你必须读完所有这些东西才能判断。

有人提到,为什么不让 AI 去审 AI?但 AI 在判断一个 issue 或 PR 是否跟项目相关、质量是否达标、是否符合项目哲学方面非常糟糕。你可以在 agents.md 里编码这些标准,但就是不行。这些判断仍然需要经过人类的大脑。

所以我搭了一套系统:不是所有人都能直接提 PR。你必须先用人类的声音开一个 issue,我读了之后回复确认,你的账号名才会被写进白名单。之后你提 PR,GitHub workflow 会检查你是否在名单上。不在的话,PR 自动关闭,附一条消息:「请先用人类的声音开一个 issue。」

这个方案很有效,因为 AI 不会回去读那条关闭 PR 时机器人发的评论。但对 issue 不适用,issue 的提交门槛更低,没法要求每个人都先经过手动审批。PR 这边基本解决了,issue 还是个难题。

文章来自于“Founder Park”,作者 “Founder Park”。

Related topics

After reading

Join the AINRK community

Read how to join the community and connect with people working in AI.

Community information (opens in a new tab)