最近把主力编码 Agent 从 Claude Code 换成了 Pi，越用越顺手，索性把从安装到高阶用法的完整笔记整理出来。Pi 是 OpenClaw 背后的编码智能体框架，官方定位是"There are many agent harnesses, but this one is yours"——让工具适应你的工作流，而不是反过来。这篇笔记会从安装配置讲起，重点放在指令追加、对话树、Skills、Extension（插件）和常用扩展包上。
1. Pi 是什么：大道至简的编码 Agent
Pi（pi.dev，仓库 earendil-works/pi）是一个开源的终端 AI 编码 Agent，MIT 协议，GitHub 已累计 9.3 万星。它的设计哲学与 Claude Code、Codex 正好相反：默认只给模型 4 个工具（read / write / edit / bash），刻意不内置子 Agent、权限弹窗、Plan 模式、MCP，把所有"可选功能"都留给 Extension 机制和社区包实现，官方把这套理念总结为"原语而非功能"（Primitives, not features）。
极简带来的是极致的上下文效率和速度：Pi 的系统提示词只有约 1000 token，说句"你好"只占 0.4% 的上下文；而同类工具光打招呼就要吃掉上万 token。第三方基准显示 Pi 完成编程任务比同类 Coding Agent 快 1.5～2 倍、单任务成本更低；Databricks 在百万行仓库上的测试里，同成本下 Pi 的成功率在多数场景优于 Claude Code 和 Codex，整张图质量最高点是 Pi + Claude Opus 的组合。
更关键的是它可改造：核心不内置 MCP、不内置 plan mode，但"你可以让 Pi 自己写一个"，或直接安装第三方 pi package。官方首页那句话就是它的灵魂——"Don't want to build it? Ask Pi to build it for you."
2. 安装与配置模型
2.1 安装
macOS / Linux 一条命令：
Windows（PowerShell）：
已自行管理 Node.js 的用户也可以用 npm（
--ignore-scripts 可避免依赖在安装时跑生命周期脚本）：装完在任意项目目录输入
pi 即启动。Pi 用 Git Bash 作为 Windows 下的命令行运行环境，若没装过 Git，安装器会询问是否帮你装好。2.2 配置模型：API Key 与订阅
启动后输入
/login 二选一：- API Key 方式：输入关键词筛出供应商（支持 Anthropic、OpenAI、DeepSeek、Kimi、MiniMax、Google Gemini、Groq、OpenRouter、Ollama 本地模型等 15+ 家），粘贴 Key 即可；
- 订阅方式：选择 Sign in with account，可接入 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 的订阅额度，浏览器完成 OAuth 登录后回 Pi 用 Ctrl+L 就能看到订阅模型。这是不额外烧 API 费用的方式之一。
会话中途可用
/model 或 Ctrl+L 打开模型选择器切模型，Ctrl+P 在收藏模型间循环；Shift+Tab 切换思考强度（off/low/medium/high 等）。模型凭据保存在 ~/.pi/agent/auth.json。3. 基础操作：把 Pi 用顺手的 12 个细节
进入 Pi 后底部信息栏依次显示：本 Session 累计输入 Token（上箭头）、输出 Token（下箭头）、缓存命中 R / 最近一次请求缓存命中率 CH、本次预估成本、当前占用上下文百分比 / 总窗口、上下文压缩策略（auto）、当前模型与思考强度。
- 换行：Shift+Enter 在输入框内换行（直接回车是发送）；Ctrl+G 打开系统编辑器（记事本/nano）编辑长提示词，保存关闭后自动同步回输入框；
- @ 引用文件：输入
@模糊搜索项目文件并附带进消息；截图沟通用Ctrl+V（Windows 用 Alt+V）粘贴图片；
- `!` 与 `!!` 命令：
!npm run dev在当前窗口临时运行命令，运行过程与结果 AI 可见；!!运行但结果不进模型上下文；
- Enter = Steering（打方向盘）：AI 执行中理解偏了，直接回车输入新指令，标着 Steering 的新指令会在当前工具步结束后注入上下文，实时纠正方向；
- Alt+Enter = Follow-up（排队）：等 AI 完成手头全部工作后才执行你排队的下一条指令。Windows Terminal 的 Alt+Enter 默认是全屏快捷键，需要先在终端设置里删掉才能用（macOS 为 Option+Enter）；排队期间可用 Alt+上箭头把指令拿回编辑框修改；
- Ctrl+O：展开/折叠工具输出；
/new新开会话（Agent 圈的经验：做完一轮任务清空好于压缩）；/compact [指令]手动压缩上下文；pi -c继续最近会话、pi -r挑选历史会话；
- 非交互一次性模式：
pi -p "查询今天的天气并写到桌面"后台静默执行，适合当一次性 CLI 命令；也支持管道输入cat README.md | pi -p "总结"。
4. 会话管理与对话树：分支、回滚、跨会话记忆
4.1 对话树
Pi 的每个 Session 是树状结构而非线性记录，全部历史存在同一个 JSONL 文件里。输入
/tree 进入对话树：选中任意历史节点回车即可回退到该状态并继续，选择时提供"不总结 / 让 AI 总结 / 自定义总结方式"三种模式（总结只针对被丢弃的那条分支，不影响其他分支）。/fork 从某个历史节点复制出新 Session 文件，/clone 把当前活跃分支整体复制为新 Session。注意：回退对话历史不会回退已写出的代码文件。要完整回滚请配合 git——先用
/tree 回到历史节点，再 !git reset --hard <commit> 把代码也退回去。这套"树 + git"组合是探索多方案的最佳姿势：同一个需求可以 fork 出多个分支分别试不同写法，互不污染。4.2 跨 Session 记忆：AGENTS.md
每个新 Session 都是空上下文，所以要在项目根目录放一个
AGENTS.md——它会在每次对话时自动加载，Codex / OpenCode 等工具通用。内容可以是项目说明、约定、甚至用户画像（"我是前端小白，网页问题要用大白话解释"）。复杂项目可以直接让 Pi 通读代码库后自己生成这份文件。让 AGENTS.md 对所有项目生效，就写到 ~/.pi/agent/AGENTS.md（全局）；想追加优先级更高的系统提示词，用 ~/.pi/agent/APPEND_SYSTEM.md。写完 /reload 热重载即可。5. 四层扩展机制速查
Pi 的扩展体系从轻到重共四层，写起来难度递增、能力也递增：
层 | 载体 | 写起来要 | 何时用 |
Skill | Markdown（SKILL.md） | 5 分钟 | 把"某类任务怎么做"的步骤/清单按需投喂给模型 |
Prompt Template | Markdown（`*.md`） | 2 分钟 | 把每天手打的那段提示词变成 `/foo 参数` |
Extension | TypeScript 模块 | 30 分钟～数天 | 注册自定义工具、拦截 Agent 循环、画 TUI、做 RPC |
Package | npm 包 | 1 小时 | 把上面三种打包，`pi install` 一键分享安装 |
经验口诀：能用 Skill 就别写 Extension；能用 Prompt Template 就别写 Skill。加载优先级是"项目级 > 全局 > 包"，
pi install 装到项目目录加 -l（local），否则装全局对所有项目生效。每装一个扩展/技能都会增加一点系统提示词负担，用不到的项目建议装到项目级，或用 pi config 关闭。6. 常用插件与好用的扩展包
Pi 官方包市场 pi.dev/packages 已收录 3000+ 个包，下面是我实际安装后筛选出的高价值清单（均支持
pi install npm:<包名> 一键安装，装完 /reload 生效）：- pi-web-access（联网全家桶，几乎必装）：Web 搜索、URL 抓取转 Markdown、YouTube 转录、PDF 提取、GitHub 仓库克隆。零配置——内置 Exa MCP 服务且无需 API Key，装上就能搜。要卸载就把 install 改成 uninstall；
- pi-subagents（多子代理并行）：
/pi-subagents让主 Agent 派多个 worker 并行开发/研究，支持 single / chain（流水线）/ parallel / async 等模式，附带的 skill 会教模型如何编排；
- pi-mcp-adapter（补上 Pi 没有的原生 MCP）：自动读取项目里的
.mcp.json，把任意 MCP Server（高德地图、数据库、内部 API 等）接进来。例如配置高德 MCP 后，问"太平角公园到崂山仰口怎么坐公共交通"，Pi 就能查坐标并规划路线。社区也有把它用于接入 Claude Code skills 的迁移场景；
- btw 插件（旁路对话）：AI 紧张干活时开一条不影响主任务的旁路提问，输入
/btw即可，很像 Claude Code 的同名功能；
- Plan Mode 插件：AI 先写 PLAN.md 跟你对齐方案、不直接动手，确认后再关掉计划模式开始执行，适合大改动；
- @narumitw/pi-goal：
/goal设定大目标（如"做一个坦克大战游戏并迭代到接近红白机效果"），Pi 会跨多轮自主推进直到完成，期间自动记录迭代历史；
- pi-dynamic-workflows：把 Claude Code 的 Dynamic Workflows 搬过来，写一段 JS 编排脚本即可调度十几个子 Agent 协同做长任务（如调研 22-26 年 AI 顶会论文），用
/workflows看每个 worker 的运行状态；
- @juicesharp/rpiv-todo：给模型一个持久化 TODO 浮层列表，扛得住
/reload和上下文压缩；
- pi-lens：给 Pi 加上"IDE 的眼睛"——基于 ast-grep 的结构化搜索替换、tree-sitter 语法检查、LSP 类型诊断，改代码前先查错；
- @narumitw/pi-statusline：替换默认状态栏，常显模型、git 分支、上下文占用、费用等信息。
此外还有：即时通信类插件可把 Pi 接到手机（
/wechat login 扫码配对后手机随时下发任务）；Edge-TTS 技能可零成本文本转语音；pi-marketplace 能在 Pi 内直接搜索、安全审计、安装 npm 上的包。7. 自己动手：让 Pi 给你写插件
Pi 最有趣的地方是它不仅能装插件，还能自己给自己写插件——它内置了扩展开发的全部知识。放到
.pi/extensions/（项目级）或 ~/.pi/agent/extensions/（全局）即可被自动发现，/reload 热加载，完全不用重启。一个 Extension 就是一个导出默认函数的 TypeScript 文件：
几个真实玩法：让 Pi 写一个"每次写/改文件后自动跑 Prettier"的插件；写一个保护
.env 的插件（模型尝试读写就直接阻止）；写一个"执行 rm 前先弹窗询问"的确认插件；甚至写一个把天气/坐标实时显示在对话框顶部的 UI 插件。全部可以直接用自然语言描述需求让 Pi 完成——说清楚需求，通常是几个文件、几十行代码，/reload 即生效。写好后加个带 pi-package 关键字的 package.json 就能发到 npm 分享。8. Skills：沉淀属于你的技能库
Skill 遵循 Agent Skills 开放标准，Claude Code / Codex 的技能目录可以直接复用（在 settings.json 里加一行路径即可）。目录结构：
SKILL.md 的 frontmatter 里
description 是最重要的字段——它决定模型何时触发这个技能，要同时写清"做什么"和"何时用"。正文采用渐进式披露：Pi 启动时只把每个技能的 name + description（约 100 token）注入系统提示词，模型判断任务匹配后才用 read 读取全文。这样装 100 个技能也几乎不占常驻上下文。用不到想省 token 的技能可以关闭，或用 disable-model-invocation: true 让某个高风险的技能只允许 /skill:名字 手动唤起（比如"部署生产"这种）。找现成技能可以逛 SkillHub / agentskills 生态，装了 Markdown Converter、Playwright 浏览器自动化等常用技能后，告诉模型你的需求，它会自动挑技能执行——比如让 Pi 打开浏览器搜索并进入某个网站，它就会调用 Playwright skill 实际操作 Chrome。
9. 安全与沙箱：全权限背后的三道保险
Pi 的安全模型很"裸"：只有在你信任项目时才会加载项目里的
.pi 配置和技能（陌生目录启动会询问是否信任）；一旦运行，默认没有权限弹窗、没有沙箱，以你的用户身份全权限执行。这是有意为之——核心保持极简高效。如果你需要安全边界，官方推荐三种容器化方式：- Gondolin Extension（推荐）：Pi 进程和模型凭据留在宿主机，把 read/write/edit/bash 及
!命令路由进本地 Linux 微虚拟机执行，文件通过挂载回写，隔离性强且对用户透明；
- Plain Docker：整个 Pi 进程跑在容器里，
-v $(pwd):/workspace挂载项目，最简单；
- OpenShell：把整个 Pi 进程放进策略控制的沙箱，适合企业合规场景。
进阶用户也可以安装权限类插件（如 pi-permission-system），让敏感操作先弹审批窗再执行——代价是会拖慢效率，我本人不用，但关键项目值得开。
10. Web UI 与更多入口
不习惯命令行的话，社区有 star 4.2k 的 Pi Web UI 项目，npx 启动后浏览器即用：左上切项目、左下文件树、支持添加模型 Provider（如 Kimi）、管理技能与插件的开关、截图粘贴、调整思考强度、显示 token 与费用，日常操作和 TUI 几乎一致，适合团队共享或远程使用。
11. 避坑与常见问题
- 版本更新极快：Pi 处于 0.x 快速迭代期，API 偶有破坏性变更。升级后先
pi update，改过自定义插件的话关注 changelog；
- Windows 下 Alt+Enter 被系统占用：先在 PowerShell 设置里删除"全屏"快捷键，否则 Follow-up 无法触发；同时建议用 Windows Terminal 获得最佳体验；
- Extension 改了没生效：放好文件后输入
/reload而不是重启；排错用/debug（日志写到~/.pi/agent/pi-debug.log）；
- 装了技能/插件模型却"看不见"：每装一个扩展都会加重系统提示词，检查是否装到了全局而当前项目不想用；用
pi config或工具开关把用不到的先关掉；
- extension 里 import 报错：开发扩展时核心依赖（
@earendil-works/pi-coding-agent等）应放 peerDependencies，别 bundle 进自己的包，否则会出现双份运行时。
12. 小结
Pi 值不值得从 Claude Code / Codex 迁过来，取决于你的诉求：想要多模型自由、深度定制工具与行为、会话树分支探索、以及不被厂商锁定的备选——Pi 目前是最合适的开源选择；若你只需要开箱即用且已深度绑定某家生态，那留在原工具也不亏。我个人的体会是：真正让人上瘾的不是它"少"，而是它把所有"多"都交到了你手上——装什么、写什么、让它变成什么样子，都由你说了算。这也正是它官网那句口号的意义：它适应你的工作流，而不是你适应它。
参考来源
*笔记整理日期：2026-09-08。Pi 处于快速迭代期，具体命令与参数以 pi.dev 官方文档为准。*