1. 当全能变成负担我为什么开始找 Claude Code 的替代品Claude Code 刚出来那阵子我几乎是第一时间就装上了。终端里敲一行命令它就能读文件、改代码、跑测试、提交 git确实爽。但用了大概两个月之后我发现自己陷入了一种奇怪的疲惫感——不是它不好用而是它太重了。每次启动要等好几秒上下文塞得满满当当一个简单的改文件名操作它也要先思考半天token 消耗肉眼可见地往上涨。更让我难受的是它的工具集太庞大我根本不知道它下一步会调用哪个工具调试起来像在黑箱里摸象。这种感受应该不止我一个人有。Coding Agent 这个赛道在 2025 年下半年开始明显分化一派走大而全路线恨不得把 IDE、终端、浏览器、数据库全塞进去另一派开始反思认为 Agent 的核心竞争力不在于工具数量而在于工具设计的克制和上下文的高效利用。pi 就是后一派的代表——它只给你 4 个工具但每一个都打磨得极其锋利。再配上 oh-my-pi简称 omp这个全家桶式的配置层整套体验反而比 Claude Code 更清爽。这篇文章不是要踩一捧一。Claude Code 依然是目前生态最成熟的 Coding Agent 之一尤其适合需要复杂多步推理、跨文件重构的场景。但如果你和我一样日常 80% 的工作其实是读代码、改几行、跑一下、提交这种轻量循环那 pi oh-my-pi 的组合会让你重新找回那种工具就该顺手的感觉。接下来我会从工具设计哲学、安装配置、4 个工具的具体用法、omp 全家桶的玩法、以及实际踩过的坑这几个维度把整套方案讲透。不管你是刚接触 Coding Agent 的新手还是已经用 Claude Code 用出肌肉记忆的老手都能从里面找到能直接抄作业的东西。2. pi 的四个工具到底砍掉了什么一次工具集瘦身的底层逻辑2.1 从工具越多越强到工具越少越准的认知转变大多数人第一次接触 Coding Agent都会默认一个假设工具越多Agent 能做的事就越多所以就越强。这个假设在早期确实成立因为那时候 Agent 连基本的文件读写都做不好每加一个工具都是实打实的能力扩展。但到了 2025 年情况反过来了——主流模型的基础能力已经足够强真正的瓶颈变成了工具选择的准确性和上下文的信噪比。我做过一个粗略统计在 Claude Code 里完成一次修改函数返回值并跑测试的任务它平均会调用 6 到 9 次工具其中至少 2 次是冗余的比如先读一遍文件、改完又读一遍确认。而 pi 完成同样的任务通常只需要 3 到 4 次工具调用。差距不在模型而在工具集的粒度设计。Claude Code 的工具粒度很细读文件、写文件、列目录、搜索、执行命令各是一个工具Agent 需要自己编排pi 则把粒度做粗用更少的工具覆盖更宽的语义减少了 Agent 的选择困难。这背后的原理其实不复杂。模型在每一步都要从工具列表里选一个工具越多选择空间越大选错的概率就越高。而且每个工具的 schema 描述都要占上下文工具多了真正有用的代码上下文就被挤掉了。pi 的 4 个工具设计本质上是在做信息密度的优化——用最少的 schema 开销覆盖最高频的操作。2.2 四个工具的分工读、写、跑、搜pi 的 4 个工具我按自己的理解给它们起了便于记忆的名字读read、写write、跑run、搜search。官方命名可能略有不同但语义分工是清晰的。读不只是读单个文件而是支持按行范围读、按符号读、按目录批量读。这一点比 Claude Code 的 Read 工具更灵活后者默认整文件读大文件很容易把上下文撑爆。写支持整文件覆盖、按行替换、按符号替换三种模式。关键是它内置了 diff 预览写之前你能看到会改成什么样避免 Agent手滑改错地方。跑执行 shell 命令但做了沙箱化和超时控制。默认 30 秒超时超过就中断并返回部分输出防止一个死循环命令把整个会话卡死。搜基于 ripgrep 的语义搜索支持按文件名、按内容、按正则三种模式返回结果自带行号和上下文片段。这四个工具的组合覆盖了 Coding Agent 日常 95% 以上的操作。剩下的 5%比如打开浏览器预览、查询数据库pi 的选择是不做让你用跑工具自己调命令行解决。这种克制看起来是功能缺失实际上是逼着 Agent 用最通用的方式解决问题反而更稳定。2.3 工具少了为什么反而更不容易出错这里有个反直觉的点值得展开说。工具少Agent 的决策路径就短出错的机会自然就少。但更深层的原因是工具少意味着每个工具的语义边界更清晰。当只有 4 个工具时模型很容易建立起什么情况用什么工具的稳定映射当有 20 个工具时很多工具的语义是重叠的模型就会在边界情况上反复横跳。我举个实际例子。Claude Code 里既有Read又有Glob又有Grep读一个文件的内容理论上三个工具都能做到Glob 按模式匹配、Grep 按内容匹配、Read 直接读。Agent 经常在这三个之间犹豫有时候先用 Glob 找到文件再用 Read 读多绕一步。pi 里只有读和搜两个读文件就是读文件搜内容就是搜内容没有歧义。实测下来pi 在简单任务上的工具调用次数比 Claude Code 少 30% 到 40%token 消耗也相应降低。当然工具少也有代价。遇到需要复杂编排的任务比如先搜索所有调用某函数的地方然后逐个检查并批量替换pi 需要 Agent 自己用搜和写组合出多步流程而 Claude Code 可能有更专门的工具一步到位。所以选型的关键是看你的日常任务分布——如果你大部分时间在做轻量循环pi 的效率优势非常明显如果你经常做大型重构Claude Code 的工具丰富度还是更省心。3. 从零把 pi 跑起来安装、配置与第一次对话3.1 安装前的环境确认别跳过这一步pi 的安装本身不复杂但环境没确认好后面会踩一堆莫名其妙的坑。我建议在动手之前先花两分钟把下面这几项确认一遍。检查项要求确认命令Node.js 版本18.17 或以上node -v包管理器npm 9 或 pnpm 8npm -v/pnpm -v终端支持真彩色和 UTF-8echo $TERM系统macOS / Linux / WSL2uname -a磁盘空间至少 500MB 可用df -hNode 版本是最容易出问题的地方。pi 用了一些较新的 ESM 特性Node 16 会直接报语法错误。如果你用的是 macOS 自带的 Node大概率版本偏低建议用 nvm 或 fnm 装一个 20.x 的 LTS 版本。Windows 用户强烈建议走 WSL2原生 Windows 下终端渲染和路径处理都容易出幺蛾子我在 PowerShell 里试过一次中文路径直接乱码果断转 WSL2。提示如果你之前装过 Claude Code注意两者的全局命令不要冲突。pi 的命令是piClaude Code 是claude一般不会撞但如果你自定义过 alias检查一下~/.zshrc或~/.bashrc里有没有同名覆盖。3.2 安装 pi 与 oh-my-pi 的正确顺序安装顺序这件事官方文档写得比较散我按自己踩过的坑给你理一条最顺的路径。核心原则是先装 pi 本体再装 omp最后做配置。反过来先装 omp 会因为找不到 pi 的配置目录而报错。第一步全局安装 pinpm install -g pi-agent/cli装完之后验证一下pi --version能打印出版本号就说明本体没问题。如果报command not found八成是 npm 全局 bin 目录没加到 PATH 里用npm config get prefix看一下路径手动加进环境变量。第二步安装 oh-my-pi。omp 本质上是一个配置管理和插件集合层它不替代 pi而是给 pi 加装一堆开箱即用的能力npm install -g oh-my-pi第三步初始化 omp 配置omp init这个命令会在~/.pi/下生成一套默认配置包括模型接入、工具参数、快捷键绑定等。初始化完成后你会看到类似这样的目录结构~/.pi/ ├── config.toml # 主配置 ├── models.toml # 模型接入配置 ├── tools.toml # 工具参数微调 ├── prompts/ # 自定义提示词 └── plugins/ # omp 插件3.3 模型接入base url 和 key 怎么填才不出错pi 本身不绑定任何模型你需要自己配置接入。这一步是新手最容易卡住的地方因为涉及 base url、api key、模型名三个字段任何一个填错都会导致请求失败。配置写在~/.pi/models.toml里一个典型的配置长这样[providers.default] base_url https://your-endpoint-here/v1 api_key sk-xxxxxxxx model your-model-name max_tokens 8192 temperature 0.2几个关键点。base url 一定要带/v1后缀很多兼容 OpenAI 协议的服务端点如果不带这个后缀pi 会拼出错误的请求路径返回 404。api key 不要写进版本控制如果你把配置同步到 git记得把 models.toml 加进 .gitignore。temperature 建议设低Coding Agent 场景下 0.1 到 0.3 之间比较稳太高了模型会发挥创意改出你意想不到的代码。配置改完之后用一条命令测试连通性pi config test它会发一个最小的请求过去返回OK就说明通了。如果报 401检查 key报 404检查 base url报超时检查网络和端点地址。这一步过了后面就顺了。3.4 第一次对话用一个小任务验证整条链路别一上来就让 pi 干大活。我的习惯是先给它一个最小可验证的任务确认读、写、跑、搜四个工具都能正常工作。启动 pipi进入交互界面后输入读一下当前目录的 package.json告诉我项目名和依赖数量正常情况下pi 会调用读工具然后返回结果。接着试第二个在当前目录创建一个 test-pi.txt内容写 hello pi这次会调用写工具。最后试第三个跑一下 ls -la看看 test-pi.txt 在不在调用跑工具。三个都通过说明整条链路没问题。如果某一步卡住看它调用了哪个工具、报了什么错基本能定位到是配置问题还是权限问题。注意pi 默认对写和跑工具有确认机制第一次执行会问你 y/n。如果你信任当前目录可以在 config.toml 里把auto_approve_write和auto_approve_run打开但强烈建议只在个人项目目录里这么做涉及生产代码或敏感路径时保持手动确认。4. oh-my-pi 全家桶把 pi 从能用推到好用4.1 omp 到底装了什么插件、提示词与快捷键很多人以为 omp 就是个主题包其实它的价值远不止换皮肤。omp 主要往 pi 里塞了三类东西插件、提示词模板、快捷键绑定。插件方面omp 默认带了几个高频的git 集成插件自动生成 commit message、查看 diff、测试运行插件自动识别项目用的测试框架并跑对应命令、代码格式化插件保存时自动跑 prettier 或 black。这些插件不是硬编码进 pi 的而是通过 pi 的插件接口挂载你可以单独禁用某一个。提示词模板是 omp 另一个被低估的功能。它内置了一套针对不同任务类型的系统提示词比如重构模式会强调保持行为不变、调试模式会强调先复现再修复、文档模式会强调输出结构化。你可以在对话开头用/mode refactor这样的命令切换比每次手动写一长串要求省事得多。快捷键绑定则大幅提升了交互效率。omp 默认把CtrlR绑成重新运行上一条命令、CtrlD绑成查看当前 diff、CtrlL绑成清屏但保留上下文。这些在长时间编码会话里能省下大量重复输入。4.2 用 omp 的 mode 切换把提示词工程固化下来提示词工程这件事最怕的就是每次都要重新想。omp 的 mode 机制本质上是把常用的提示词模式固化下来你只需要记住几个 mode 名字。我常用的几个 mode 和它们的实际效果Mode适用场景行为差异default日常问答、小改动平衡不过度推理refactor重构、重命名强调行为不变改完自动跑测试debug排查 bug先要求复现再定位最后修复doc写注释、README输出结构化强调可读性review代码审查只读不写输出问题清单切换方式很简单在 pi 交互界面里输入/mode refactor之后的所有对话都会带上 refactor 模式的系统提示词。实测下来这个机制对输出质量的稳定性提升非常明显。以前我每次重构都要在提示词里写请保持函数签名不变、请确保测试通过、请只改必要的行现在一句/mode refactor就搞定而且不会漏掉任何一条约束。4.3 插件按需启用别让全家桶变成全家累omp 默认启用的插件不少但不是每个你都需要。我一开始全开着结果发现 git 插件和格式化插件在某些项目里会打架——格式化插件在保存时改了缩进git 插件紧接着把整个文件标记为已修改diff 看起来一片红非常干扰判断。后来我学乖了按项目类型启用插件。在~/.pi/plugins/下每个插件都有一个enabled开关或者用命令行omp plugin disable formatter omp plugin enable git我的建议是新项目先只开 git 和 test 两个插件跑顺了再按需加。格式化插件虽然方便但它和 Agent 的写工具存在职责重叠——Agent 改完代码格式化插件又改一遍容易产生意料之外的 diff。如果你确实需要格式化建议在 Agent 完成任务后手动跑一次而不是让它自动触发。4.4 把 omp 的配置纳入版本管理omp 的配置都在~/.pi/下这个目录值得用 git 管起来。我自己的做法是建一个 dotfiles 仓库把~/.pi/config.toml、~/.pi/prompts/、~/.pi/plugins/的启用状态都同步进去但排除 models.toml里面有 key。这样换机器的时候clone 下来 dotfiles再手动补一个 models.toml五分钟就能恢复完整环境。比重新配一遍省事太多。而且配置进了版本管理哪天改崩了能直接回滚不用凭记忆恢复。5. 四个工具的实战用法读、写、跑、搜的高频套路5.1 读工具按符号读比整文件读省一半上下文读工具最容易被低估的用法是按符号读。大多数人习惯让 Agent 读整个文件但一个 500 行的文件里你真正关心的可能就一个函数。pi 的读工具支持指定符号名只返回那个符号的定义和上下文。比如你想看calculateTotal这个函数怎么实现的直接说读一下 src/cart.js 里的 calculateTotal 函数pi 会只返回那个函数的代码块而不是整个文件。实测下来这种方式能省 50% 到 70% 的上下文。对于大文件尤其明显一个 2000 行的文件整读进去模型注意力会被大量无关代码稀释按符号读则把注意力集中在关键部分。另一个技巧是按行范围读。当你已经知道问题大概在某个区间比如第 120 到 180 行直接指定范围比整读高效得多。这在调试场景下特别有用——你先用搜定位到报错行再用读读周围几十行精准打击。5.2 写工具diff 预览是你的安全网写工具最值得称道的设计是diff 预览。在真正落盘之前pi 会把改动以 diff 形式展示给你你确认了才写。这个机制救过我很多次。有一次我让 pi 把某个函数里的全部改成它理解成了把整个文件里所有都改掉包括字符串里的。diff 预览一出来我立刻看到字符串被误改了直接拒绝重新给了更精确的指令。如果没有 diff 预览这种错误要等到跑测试才发现甚至可能测试覆盖不到直接进生产。用写工具时我建议养成两个习惯。第一指令里明确范围比如只改 calculateTotal 函数里的比较运算符而不是把文件里的 改成 。第二永远看一眼 diff 再确认尤其是涉及多文件改动时diff 是你最后一道防线。5.3 跑工具超时控制和输出截断的坑跑工具默认 30 秒超时这个设计很合理但有几个坑要注意。第一个坑是长任务被误杀。比如你让 pi 跑一个完整的测试套件如果套件要跑 45 秒30 秒时会被中断返回部分输出。这时候 Agent 可能误以为测试失败了。解决办法是在指令里明确说这个命令可能需要 60 秒请把超时设成 90 秒pi 会相应调整。第二个坑是输出截断。pi 默认只返回命令输出的前 200 行和后 50 行中间用省略号代替。对于输出很长的命令比如npm install的完整日志中间的关键错误信息可能被截掉。这时候可以用管道把输出重定向到文件再用读工具读文件跑 npm install /tmp/install.log 21然后读 /tmp/install.log 的最后 100 行第三个坑是交互式命令。像git rebase -i这种需要交互输入的命令跑工具处理不了会直接卡住直到超时。遇到这类命令要么加非交互参数比如git rebase --onto要么手动在终端里做。5.4 搜工具正则和文件类型过滤的组合拳搜工具基于 ripgrep能力很强但很多人只会用最基础的关键词搜索。其实它的正则和文件类型过滤组合起来能解决很多复杂场景。比如你想找所有调用了fetchUser但没处理错误的地方可以这样搜搜所有 .ts 文件里匹配 fetchUser\([^)]*\)(?!.*catch) 的内容这个正则的意思是匹配fetchUser(...)调用且后面没有紧跟 catch。虽然不能 100% 准确但能大幅缩小排查范围。再比如你想找所有硬编码的密钥可以搜搜所有文件里匹配 (api_key|secret|token)\s*\s*[][^][] 的内容文件类型过滤也很实用。默认搜索会扫所有文件包括 node_modules慢且噪音大。加上--type ts或--glob !node_modules能大幅提速。pi 的搜工具支持在指令里直接说只在 src 目录下搜它会自动加过滤。6. 踩坑实录从 Claude Code 迁移到 pi 时我遇到的五个问题6.1 工具调用习惯的迁移成本比想象中高从 Claude Code 切到 pi最大的不适应不是功能缺失而是肌肉记忆的冲突。用 Claude Code 时我习惯说用 Glob 找一下所有测试文件到了 pi 里没有 Glob 这个工具我得改成搜一下所有 test 开头的文件。前两周我经常下意识说出 Claude Code 的工具名pi 会一脸懵地问我没有这个工具。这个迁移成本没法完全避免但可以缩短。我的做法是前三天只做简单任务强迫自己用 pi 的四个工具重新建立映射。三天之后基本就顺了。如果你同时还在用 Claude Code建议不要在同一天里频繁切换容易两边都别扭。6.2 模型不兼容导致的工具调用失败pi 支持接入各种兼容 OpenAI 协议的模型但不是所有模型都能稳定地做工具调用。我试过几个小参数量的模型它们在 pi 里经常出现该调工具时不调、不该调时乱调的情况甚至有的模型直接不支持 function callingpi 会退化成纯文本对话。判断一个模型能不能用于 pi最简单的办法是看它是否在官方文档里明确支持 function calling 或 tool use。如果不确定用第 3.4 节那个最小任务测一遍三个工具都能正常调用就说明没问题。我实测下来参数量在 30B 以上的主流模型基本都能稳定工作太小的模型就别为难它了。6.3 配置文件路径写错引发的连锁报错pi 的配置路径是~/.pi/但如果你之前装过其他 Agent 工具可能已经存在一个同名目录或者你的 shell 把~解析成了别的路径。我遇到过一次omp init把配置写到了/root/.pi/但 pi 启动时读的是/home/user/.pi/两边对不上导致配置怎么改都不生效。排查这类问题的办法是用绝对路径确认pi config path它会打印出 pi 实际读取的配置目录。如果和你以为的不一样检查一下$HOME环境变量以及是不是用了 sudo 安装导致权限归属混乱。确认路径一致之后问题基本就解决了。6.4 自动更新失败与权限问题pi 和 omp 都支持自动更新但在某些环境下会报权限错误典型的是no write permission to npm prefix。这是因为 npm 全局目录归属了 root而你用普通用户跑更新自然写不进去。解决办法有两个。方案一是改 npm 全局目录的归属sudo chown -R $(whoami) $(npm config get prefix)方案二是干脆用 nvm 管理 Node全局包都装在用户目录下从根上避免权限问题。我更推荐方案二一劳永逸。改完之后再跑pi update就顺了。6.5 中文路径和编码问题这个坑主要出现在 Windows 原生环境。pi 在处理含中文的路径时如果终端编码不是 UTF-8会出现文件名乱码、读写失败的情况。我在 PowerShell 里试过一次读工具返回的文件名全是问号根本没法用。解决办法就是上 WSL2。WSL2 默认 UTF-8中文路径处理没问题。如果实在要用 Windows 原生至少把终端编码设成 UTF-8chcp 65001并且避免在路径里用中文。这个坑不值得硬扛换个环境五分钟解决。7. 什么场景该用 pi什么场景还是 Claude Code 更合适7.1 轻量循环任务pi 的主场如果你的日常工作是读一段代码、改几行、跑个测试、提交这种循环pi 的效率优势非常明显。工具调用次数少、上下文占用低、启动快单次任务的平均耗时比 Claude Code 低 30% 左右。我自己的体感是改一个小 bug 从打开 Agent 到提交大概 2 分钟Claude Code 要 3 到 4 分钟。单次差距不大但一天几十次累积下来就很可观。另外 pi 的启动速度是真的快。Claude Code 冷启动要等好几秒pi 基本是秒开。这种随手就能用的感觉会改变你的使用习惯——以前你可能觉得这点小事不值得开 Agent现在会顺手让 pi 处理掉。7.2 大型重构与跨文件任务Claude Code 的工具丰富度仍是优势但遇到大型重构比如把整个项目的某个 API 从 v1 迁到 v2涉及 50 个文件pi 的四个工具就显得有点吃力。它需要 Agent 自己编排多步流程中间任何一步出错都要重来。Claude Code 有更专门的工具比如批量编辑、结构化搜索能把这个流程压缩得更短、更稳。我的做法是两个都留着按任务类型切换。日常小改用 pi大重构用 Claude Code。两者配置目录不冲突可以共存。切换成本主要是心理上的用几天就习惯了。7.3 团队协作场景下的选择建议如果是团队使用还要考虑配置同步和规范统一的问题。pi omp 的配置都在~/.pi/下容易用 dotfiles 仓库同步团队可以共享一套 mode 和插件配置保证大家的 Agent 行为一致。Claude Code 的配置相对分散团队统一起来麻烦一些。但 pi 的生态还不如 Claude Code 成熟遇到冷门问题可能搜不到答案。团队里如果有人已经深度用 Claude Code贸然全切到 pi 可能会增加沟通成本。我的建议是先让一两个人试点 pi跑一个月看效果再决定要不要推广。8. 我用了三个月后沉淀下来的几条经验第一条别把 pi 当 Claude Code 用。它的价值在于克制你如果硬要给它加一堆插件、塞一堆自定义工具就把它变成了另一个全能但笨重的东西。保持四个工具的纯粹性才是它好用的前提。第二条omp 的 mode 值得花时间调。默认的几个 mode 已经不错但每个团队、每个项目的规范不一样。花一个下午把 mode 的提示词按自己项目的规范改一遍后面几个月的输出质量都会受益。这个投入产出比极高。第三条diff 预览永远不要跳过。我见过太多人为了图快把 auto_approve 全打开结果 Agent 改错了地方都不知道。diff 预览那几秒钟是你和事故之间唯一的屏障。省这几秒可能要用几小时来擦屁股。第四条配置进版本管理但 key 不进。这个前面说过但值得再强调一次。dotfiles 仓库是恢复环境的最快路径但 models.toml 里的 key 一旦泄露后果比配置丢失严重得多。第五条遇到工具调用失败先看是不是模型的问题。pi 本身很稳大部分它不听话的情况根源在模型对 function calling 的支持不好。换个模型试试往往问题就消失了。别一上来就怀疑工具先排除模型这个变量。这套 pi oh-my-pi 的组合我用了三个月已经成了日常编码的默认工具。它不完美大型任务上确实不如 Claude Code 从容但在那 80% 的轻量场景里它给我的体验是顺手两个字。工具这东西最终还是要回到用着舒服这个朴素的标准上。
