Pi Agent 安装指南,3分钟跑起来

此视频使用pi+hyperframes直出

（下期会讲解如何使用pi-web制作此视频）

一、前置准备：Node.js 环境

Pi 是 Node.js 项目，装之前先检查环境。

# 检查 Node.js 版本（需要 >= 20）node --version# 检查 npm 版本npm --version

如果版本太低，先升级 Node.js。Windows 用户推荐用 nvm-windows：

# 安装 nvm-windows 后nvm install 22nvm use 22

踩坑记录：Pi 某些版本依赖 Node.js 原生模块，Node 版本太低会导致安装失败报错。22 以上基本没问题。

二、安装命令（官方最新）

官方 pi.dev 给出了 5 种安装方式，根据你的环境选择：

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# 验证安装pi --version

pnpm

pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent

bun

bun add -g --ignore-scripts @earendil-works/pi-coding-agent

注意：--ignore-scripts 是关键参数，避免安装时的脚本执行问题。

三、配置 API Key

装好之后还跑不起来——需要配置 AI 模型的 API Key。

Pi 支持 15+ 个 provider（Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、Kimi、MiniMax、小米 MiMo 等），这里以 OpenAI 为例。

第一步：获取 API Key

去 OpenAI Platform 创建 Key，复制备用（也可配置自己的coding plan key）。

第二步：配置环境变量

# Windows (PowerShell)$env:OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"# macOS / Linuxexport OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

第三步：启动

pi

应该能看到启动界面，底部显示已连接的模型。

四、跑通第一个任务

现在进入实际使用环节。假设你在一个项目目录里，想让 Pi 帮你审查代码。

# 进入项目目录cd E:\pi-agent\demo# 启动 Pipi

进入交互界面后，输入：

帮我创建一个简单的hello world网页

Pi 会分析目录结构，读取文件，然后给你反馈。

五、几个常用命令

刚上手时，这几个命令最实用：

/model — 切换模型

/model claude-sonnet-4-20250514/model gpt-4o/model deepseek-chat/model kimi/model minimax

Pi 支持 46 个 provider，随时可以切换。快速切换用 Ctrl+L，循环浏览收藏用 Ctrl+P。

不同模型擅长不同场景：

模型	擅长场景
Claude Sonnet 4	代码审查、重构建议
GPT-4o	快速生成、结构化输出
DeepSeek V4	中文理解、长文本处理
Kimi / MiniMax	国内场景、低成本

/tree — 查看会话树

/tree

Pi 的会话是树结构存储的——可以回到任意历史节点继续对话，所有分支都在一个文件里。

这是 Pi 区别于很多 AI 工具的地方：不只能看当前对话，还能看到你之前放弃的那些分支。

/compact — 压缩上下文

长对话跑久了，Token 消耗越来越大。这时候输入：

/compact

Pi 会自动压缩对话历史，保留关键上下文，丢弃无关的来回试探。这个功能在处理大型项目时特别有用——上下文窗口有限，但项目代码可能是几十万行。

/export — 导出对话

/export

把当前会话导出为 HTML 文件，方便存档或分享给同事。

/share — 上传 Gist 分享

/share

把会话上传到 GitHub Gist，获取一个可分享的链接，别人打开能看到完整的对话记录。示例。

/settings — 调整配置

/settings

进入设置界面，可以调整：- Thinking level — 模型思考深度（影响输出质量和速度）- Theme — 终端主题- 传输协议 — HTTP/WebSocket 配置

/reload — 热重载扩展

如果装了 Skills 或自定义扩展，想要不重启就能加载更新后的内容：

/reload

六、我踩过的几个坑

坑 1：安装命令错误

之前用 npm install -g @earendil-works/pi-coding-agent（没有 --ignore-scripts），结果报错。

正确命令（来自 pi.dev）：

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

坑 2：Pi 卡在「thinking」不动

有时候终端看起来卡住了，其实是在等待模型响应。如果长时间没反应：- 检查网络能不能访问模型 API- 按 Ctrl+C 中断，重新输入- 换个模型试试

记住：Pi 本身不跑 AI 模型，它只是个「接口」——真正处理请求的是你配置的 provider。所有网络问题都是 provider 那边的。

坑 3：Windows 上 PATH 没配好

全局安装后，pi 命令找不到——Windows 上需要把 npm 全局目录加到 PATH。

# 查看全局目录npm config get prefix# 手动添加到 PATH（PowerShell）$env:PATH += ";$(npm config get prefix)\node_modules\.bin"

或者直接用 npx 方式，更省事：

npx @earendil-works/pi-coding-agent@latest

坑 4：API Key 格式问题

如果报错 Invalid API Key，检查一下：- Key 前面没有多余空格- 没有引号包裹（环境变量设置时注意）- Key 没有过期或被撤销

七、下一步学什么

装好跑通之后，可以继续研究：

多模型切换
— 不同模型适合不同场景
会话管理
— /tree / /compact / /export 怎么配合用
Skills 扩展
— 把自定义工具装进 Pi

后续会陆续出教程。

写在最后

装 Pi Agent 其实不难，难的是第一次卡住的时候不知道往哪走。

把这篇存好，下次有新同事问，直接丢链接。

不过还是建议使用 pi-web，具体的使用方式参考：pi-web：这个界面让我爱上了 Pi Agent

精选系列