进阶教程 中等 30-60分钟
用裸 Pi 自建极简 Agent
不用完整 OpenClaw，直接用其内核引擎 Pi 搭一个完全可控的极简 Agent：安装、配模型、写第一个扩展、项目级 Skills 与会话树工作法。
#Pi
#Agent Development
#TypeScript
准备工作
- Node.js 22.19+ (required by Pi)
- One LLM API key (OpenAI / Anthropic / Google, etc.)
- Terminal and CLI basics
- A clear idea of what your agent should do
操作步骤
1
安装 pi-coding-agent
Pi 的交互式 coding agent 以 npm 包发布。先确认 Node 版本，再全局安装。
命令 / 操作
All
node -v && npm install -g @earendil-works/pi-coding-agent 小提示
- • Pi's supply-chain discipline (pinned deps + shrinkwrap, --ignore-scripts installs) is part of why it has a reliability reputation.
2
首次运行与模型配置
在任意目录运行 pi，按引导填入 API Key。Pi 的 pi-ai 层统一了 OpenAI / Anthropic / Google 等多家提供商，切换模型不改代码。
命令 / 操作
All
pi 小提示
- • You can switch models mid-session; messages from different providers coexist in one session by design.
3
从官方示例扩展起步
仓库 packages/coding-agent/examples/ 内有官方示例扩展。把示例丢给 Pi，说「照这个写一个适合我的」，比从零写快得多。
命令 / 操作
Reference
https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/ 小提示
- • Pi's philosophy is self-extension: instead of downloading community extensions, point the agent at an example and have it remix it for you.
4
实践「最少扩展」原则
r/PiCodingAgent 社区共识：扩展装得越少，Pi 跑得越好。每装一个问自己「它真的更好吗」，不是就删。
小提示
- • Throw away skills you no longer need too — Armin Ronacher prunes hand-crafted skills regularly.
5
把高频操作写成项目级 Skills
在仓库内维护项目级 skills，让 Agent 在这个项目里总是按你的规范行事，团队成员 clone 即得同一套行为。
命令 / 操作
Reference
https://www.reddit.com/r/PiCodingAgent/comments/1ttv8fu/project_level_skillsextensions_are_op/ 小提示
- • The community calls project-level skills 'OP': commit-message style, changelog generation, forcing uv over pip — all great skill or interception-extension material.
6
会话树与自延展工作法
Pi 的会话是树：分支出去修一个坏掉的扩展，修完回主会话继续，不污染主上下文。让 Agent 写扩展 → 热重载 → 测试，循环到能用为止。
小提示
- • Pi can even render custom TUI components (progress bars, file pickers, preview panes) — the author ran Doom in the TUI.
常见问题
Pi 和 OpenClaw 是什么关系？
Pi 是极简 agent 引擎（内核），OpenClaw 是基于这类内核哲学构建的完整形态（渠道接入 + 7×24 自主运行）。想要「开箱即用的管家」选 OpenClaw；想完全掌控每个行为、或自己造 Agent，用裸 Pi。
Pi 没有 MCP，现有 MCP 工具怎么接？
两条路：用 mcporter 把 MCP 调用暴露成 CLI / TypeScript 绑定给 Agent 用（OpenClaw 也是这么做的）；或让 Agent 直接写一个对接 skill/扩展——Pi 的设计就鼓励这种自延展。
Pi 的权限怎么管？
Pi 出厂不带权限系统，以启动它的用户权限运行。官方建议需要强边界时做容器化/沙箱：Gondolin 扩展（微 VM 只路由工具调用）、普通 Docker 整体隔离，或 OpenShell 策略沙箱。