Claude Code 免费开源平替！极简编程智能体 Pi 上手避坑指南

用过 Claude Code 或 Codex 的朋友，应该都体会过那种“被工具按着头走”的感觉：它们确实好用，但流程是写死的，权限审批是固定的，连绑定的模型都由厂商说了算。

今天聊的 Pi（Pi Coding Agent） 走的是另一条路子。

它同样是跑在终端里的 AI 编程智能体，能听懂人话、读本地文件、跑命令、改代码。它的 npm 包名叫 @earendil-works/pi-coding-agent，敲出来的命令只有两个字母：pi。

这篇指南从零开始，带你把这个极简的开源工具装上、跑通，并避开新手最容易踩的几个大坑。

目录

1. 它跟成品智能体有什么区别？

2. 三种安装方式与初始配置

3. 终端快捷键与常用指令

4. 实操上手：从只读试探到自己改自己

5. 新手必看：7 个省钱保命的避坑指南

6. 底层包结构：想自己做产品的可以怎么拆

7. 上手路线总结

一、它跟成品智能体有什么区别？

如果把 Claude Code、Codex 比作买回来就能直接用的品牌整机，那 Pi 就是一盒散装的乐高积木。

官方给它的定位叫“最小智能体外壳（minimal agent harness）”。它的内核只保留了最基础的“思考—调工具”循环，其他花里胡哨的功能全被砍掉了——默认连计划模式（Plan Mode）、子智能体（Sub-agents）都没有，甚至连内置的权限弹窗都没做。

你想要什么功能，就自己像装插件一样往里塞。

花时间折腾它，图的主要是这四样东西：

1. 完全免费开源（MIT 协议）+ 不挑模型：随便接 Anthropic、OpenAI、Google、OpenRouter 甚至本地跑的 Ollama，哪家 API 便宜或者手头有哪家的 Key 就接哪家。

2. 对话记录是一棵树，不是一条直线：普通工具聊偏了只能重开窗口重新喂背景；Pi 的会话存成树状结构，聊到一半想换个方案试水，直接退回前面任意一个节点分叉出新分支，原来的记录一点不丢。

3. 四种调用姿势：既能在终端里聊天交互，也能用 -p 塞进自动化脚本跑一次性任务，还能走 JSON 事件流、RPC 甚至直接作为 SDK 嵌进你自己的 TypeScript 项目里。

4. 能自己改自己：因为它的扩展和配置全是存在硬盘上的明文文件，你甚至可以直接在对话里让它给自己写个新功能，敲个 /reload 热重载当场生效。

二、三种安装方式与初始配置

装之前先看一眼电脑里的 Node.js 版本，要求在 22.19 或以上。

1. 挑一条顺手的路装上

• 方式一：官方一键脚本（最推荐，省心且锁死依赖版本） macOS / Linux 打开终端敲：

curl -fsSL https://pi.dev/install.sh | sh

Windows 打开 PowerShell 敲：

powershell -c "irm https://pi.dev/install.ps1 | iex"

• 方式二：走 npm 全局安装

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

• 方式三：走 Nix 源码构建（适合 Linux / macOS 极客）

nix run github:earendil-works/pi/stable

为什么推荐第一条？ 官方脚本会严格锁定所有底层传递依赖的版本；直接走 npm install 不会锁死间接依赖，从防止开源供应链投毒的角度看，官方脚本更稳妥。

装完敲一行 pi --version，能正常蹦出版本号就算齐活。

2. 开工前先配好三件事

第一件：把模型 API 接通 直接在终端敲 pi 回车，进界面后敲 /login，跟着向导选模型厂商填 Key。如果你习惯在系统环境变量里管 Key，直接往 .zshrc 或 .bashrc 里塞也行：

export ANTHROPIC_API_KEY="你的_Claude_Key" export OPENAI_API_KEY="你的_OpenAI_Key" export GEMINI_API_KEY="你的_Google_Key"

第二件：设好默认启动模型 如果不设，它默认会去找 Google 的模型。打开（或新建）~/.pi/agent/settings.json，把平时主力用的模型写进去，比如走 OpenRouter 调 Kimi：

{ "defaultProvider": "openrouter", "defaultModel": "moonshotai/kimi-k2.6" }

第三件：做好隔离准备 再次划重点：Pi 启动后直接继承你当前系统账号的全部权限，没有任何“是否允许删除文件”的弹窗。拿它去跑陌生项目之前，务必先看一眼第五节的避坑指南。

三、终端快捷键与常用指令

敲 pi 进的是纯终端界面，没有花哨的按钮，记住这几个高频按键和斜杠命令就够用了：

核心快捷键

高频斜杠命令

/login # 登录或添加各家大模型的 API Key /model # 临时换模型 /tree # 呼出会话树，退回之前的某个对话节点重新开分支 /export # 把当前这轮对话完整导出成一页排版好的 HTML 文件 /share # 把对话一键生成 GitHub Gist 链接发给别人看 /reload # 改完扩展代码、技能或主题配色后，不重启直接热加载生效

四、实操上手：从只读试探到自己改自己

1. 选模型与调思考挡位

干活前先看手头有哪些模型能调：

# 按关键词搜一下支持的模型名字 pi --list-models kimi # 指定用 sonnet 模型，顺便把推理思考强度拉到 high（高） pi --model sonnet:high "帮我看看这段报错是怎么回事" # 限定只在指定的三个模型里用 Ctrl + P 来回切 pi --models claude-sonnet,claude-haiku,gpt-4o

它的推理强度分了七挡：off、minimal、low、medium、high、xhigh、max。平时改个简单配置用默认挡就行，遇到跨好几个文件的复杂逻辑重构再往高处拧，省得白烧 Token。

2. 第一单活：锁死只读权限，先看别动

刚进一个项目目录，别上来就让它动手改代码。先让它看一遍，探探它的理解能力：

cd 你的项目目录 pi "先读一遍项目目录结构，告诉我入口文件在哪，千万别改任何代码"

如果怕它不听话手欠乱改，启动时直接用 --tools 参数把写入工具拔掉，只给它看文件的权力：

# 只开放读取和搜索工具，彻底锁死修改和执行命令的能力 pi --tools read,grep,find,ls -p "帮我检查一下 src 目录下的代码有什么隐患"

这里有个细节要注意：Pi 默认开启的工具是 read、bash、edit、write，而专门用来搜文件的 grep、find、ls 默认居然是关着的。想让它找文件更利索，启动时可以把全套工具手动带上：

pi --tools read,bash,edit,write,grep,find,ls

3. 把对话当成 Git 分支一样耍

平时每聊一次，记录都会自动存在 ~/.pi/agent/sessions 里。建议养成给重要任务起名字的习惯：

pi --name "重构支付接口" # 开局先起个名，以后好找 pi -c "接着刚才的往下写" # 直接续上最近一次的对话 pi -r # 拉出历史会话列表，挑一个接着聊 pi --fork <会话ID> # 把某次历史对话复制分叉出一份新的，原记录保留不动

聊到中途发现思路走进死胡同了，不用关掉重来（重来还得把前面几十轮的背景再喂一遍），直接在输入框敲 /tree，把光标挪到走偏之前的那句话上回车，当场就能长出一条新分支继续试。

4. 边跑边纠偏：随时喊停与排队

很多智能体一旦开始跑任务，输入框就锁死了，看着它往错的方向一路狂奔，你只能干瞪眼或者猛按 Ctrl + C 强行掐断。

在 Pi 里，它干活时输入框依然是活的：

• 看到它准备去动不该动的数据库表，直接打字“别碰数据库，只改前端Mock数据”然后按 Enter，它会当场刹车掉头。

• 如果看它干得挺顺，你脑子里突然冒出下一步要干的事，打完字按 Alt + Enter，这句话就会安静地排在队尾，等它把眼前的活交差了立刻无缝接上。

5. 装插件：技能、扩展、模板与主题

Pi 的外挂分成了四类，全靠这四样东西长本事：

• 技能（Skills）：说白了就是一份写给 AI 看的 Markdown 操作手册（可以顺带绑几个脚本），放在 ~/.pi/agent/skills 下启动就会自动读取。

• 扩展（Extensions）：实打实的代码插件，用来给 Pi 增加新工具、新斜杠命令或新参数。

• 提示词模板（Prompt Templates）：把平时高频复用的长指令存成模板，省得天天重敲。

• 主题（Themes）：换终端界面的配色。

这四样东西可以打包成一个 Pi Package 丢到 npm 或 GitHub 上。平时安装和管理跟用手机应用商店差不多：

pi install npm:@foo/pi-tools # 从 npm 安装别人的扩展包 pi install git:github.com/badlogic/pi-doom # 直接从 GitHub 仓库拉取安装 pi list # 看看自己现在装了哪些包 pi config # 打开开关面板，按项目启用或停用某些包（按 Tab 切换作用范围） pi update # 一键升级所有已装的包 pi remove npm:@foo/pi-tools # 卸载

要是某个技能你只想当前这把临时用一下，或者今天想裸机跑不想加载任何技能，加个参数就行：

pi --skill ./skills/my-skill "按这个技能的规矩处理这批表格" pi --no-skills "这次一个技能都别加载"

6. 让它自己动手改自己

因为所有的扩展和配置都躺在本地硬盘里，你完全可以把 Pi 当成它自己的修理工。比如装了个英文扩展看着别扭，直接跟它说：

把刚才装的那个扩展里的弹窗提示全改成中文，改完保存，我自己敲 /reload。

等它改完文件，你敲一下 /reload，连终端都不用退，汉化版的新扩展当场就跑起来了。

7. 塞进自动化流水线

不想进交互界面聊天，只想让它在后台默默干完一件活就退出，用 -p（打印模式）：

# 让它读完代码生成一份总结直接存进文本，跑完自动退出 pi -p "总结一下这个仓库的核心功能" > summary.txt # 吐出标准 JSON 事件流，直接拿管道传给 jq 或其他程序接着处理 pi --mode json -p "检查 package.json 里有哪些过期的依赖" | jq

此外它原生内置了 MCP 协议（直接连外部数据库或现成工具），还带了个挺狠的 Codemode——遇到需要连续调用十几次工具的繁琐流程，它能直接把这一串调用逻辑写成一段 JavaScript 代码，丢进沙箱里一口气跑完，省掉中间一轮又一轮来回对话的等待时间和 Token 消耗。

五、新手必看：7 个省钱保命的避坑指南

这部分建议动手前先通读一遍，能少踩很多雷：

坑 1：它真的没有任何内置权限拦截！

这是最大的一个坑。Pi 跑起来就是你本机当前用户的完整权限——你能删库它就能删库，你能看私钥它就能读私钥，中间没有任何确认弹窗。 千万别在生产服务器上直接跑它，也别在存着公司核心密码本的目录下乱试。正经干活前，务必用 Docker 容器、OpenShell 或者官方推荐的 Gondolin 微虚拟机把它关在笼子里跑。

坑 2：上手觉得“怎么啥功能都没有”

从 Claude Code 转过来的人，第一反应往往是“怎么连个计划模式（Plan Mode）都没有？”。这不是软件有 bug，是作者故意全拆了。想要什么能力，去社区找对应的 Package 装上就行。

坑 3：图省事用 npm 装导致依赖版本漂移

前面提过，直接跑 npm install 不会锁死底层一层套一层的传递依赖。为了防供应链投毒，哪怕多敲几个字，也尽量用官方给的 curl ... | sh 脚本安装。

坑 4：让它找个文件怎么这么笨？

前面说了，内置的 grep、find、ls 三个搜索工具默认是关闭的。如果不手动加 --tools 打开，它为了找个文件就只能去调 bash 跑系统命令，既啰嗦又费 Token。平时常驻使用建议在配置或启动别名里把这几个工具默认打开。

坑 5：以为点了 --approve 就能保证安全

当你进到一个带有本地配置或自定义技能的陌生开源项目时，Pi 会问你要不要用 --approve 信任加载。注意：信任只代表“允许加载这个文件夹里的配置”，绝不等于“给这个项目套上了安全沙箱”。来路不明的项目，点同意前先自己翻翻 .pi 目录下有啥猫腻。

坑 6：从来不起名字，历史记录攒成乱麻

默认情况下每次对话都存盘，跑上百八十次之后，敲 pi -r 弹出来的列表全是天书，根本找不到上周改半截的那个对话。长任务进门先敲 --name "任务名"，工作项目和个人折腾用 --session-dir 分开不同文件夹存。

坑 7：刚装好敲 pi 直接卡在登录页不动

因为没改配置前它默认找 Google 的模型，你电脑里又没配 Google 的 Key，自然就卡住了。第一次启动要么老老实实敲 /login 配好账号，要么启动时直接带上厂商和模型名，比如 pi --model openai/gpt-4o-mini。

六、底层包结构：想自己做产品的可以怎么拆

如果你不仅想用它，还想基于它自己攒一个公司内部的编程助手，其实 Pi 底层是被拆成好几个独立 npm 包发布的：

想自己套个网页壳或者桌面客户端，完全可以只拿 pi-ai 加 pi-agent-core 当发动机，外面的界面自己随便画。

七、上手路线总结

不用被这么多参数吓到，今天想尝鲜的话，按这四步走最稳当：

1. 装软件配模型：用官方脚本装好，敲 pi 进去用 /login 把手头有的模型 Key 填上跑通。

2. 先只读试水：找个不重要的本地小项目，带上 --tools read,grep,find,ls 让它先帮你读代码、找问题，看看它的成色。

3. 试一次装包和热重载：去装一个现成的扩展或技能包，或者让它改一下自己的提示词再敲 /reload，体会一下什么叫“积木式智能体”。

4. 套上容器再放权：确认把 Docker 或隔离环境配明白了，再放开手脚让它替你批量改代码。

如果你只想找个保姆工具马上干活，Claude Code 和 Codex 依然是最省心的选择；但如果你烦透了被固定流程绑架，想亲手调教出一个完全贴合自己习惯的趁手兵器，Pi 绝对值得你花一个周末好好盘一盘。

作者提示含AI生成内容。作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～