编辑文档 - Pi Agent 安装指南，3分钟跑起来

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

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

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

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

# 检查 npm 版本
npm --version
```

如果版本太低，先升级 Node.js。Windows 用户推荐用 [nvm-windows](https://github.com/coreybutler/nvm-windows)：

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

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

---

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

官方 [pi.dev](https://pi.dev) 给出了 5 种安装方式，根据你的环境选择：

### macOS / Linux（推荐）

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

### Windows PowerShell

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

### npm（通用方式）

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

# 验证安装
pi --version
```

### pnpm

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

### bun

```bash
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](https://platform.openai.com/api-keys) 创建 Key，复制备用。

**第二步：配置环境变量**

```bash
# Windows (PowerShell)
$env:OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

# macOS / Linux
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
```

**第三步：启动**

```bash
pi
```

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

---

## 四、跑通第一个任务

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

```bash
# 进入项目目录
cd C:/Users/你的用户名/你的项目

# 启动 Pi
pi
```

进入交互界面后，输入：

```
帮我看一下 src 目录下的代码有什么潜在问题
```

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

---

## 五、几个常用命令

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

### /model — 切换模型

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

Pi 支持 15+ 个 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，获取一个可分享的链接，别人打开能看到完整的对话记录。[示例](https://pi.dev/session/#0ea51497613daf7e1de28ee99950b074)。

### /settings — 调整配置

```
/settings
```

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

### /reload — 热重载扩展

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

```
/reload
```

---

## 六、我踩过的几个坑

### 坑 1：安装命令错误

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

**正确命令**（来自 [pi.dev](https://pi.dev)）：

```bash
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。

```bash
# 查看全局目录
npm config get prefix

# 手动添加到 PATH（PowerShell）
$env:PATH += ";$(npm config get prefix)\node_modules\.bin"
```

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

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

### 坑 4：API Key 格式问题

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

---

## 七、下一步学什么

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

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

后续会陆续出教程。

---

## 写在最后

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

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

---

## 评论区预置内容

PowerShell 装 Windows 版最稳
3分钟确实装好了
/model 怎么切模型来着
compact 确实好用，长对话必用

摘要

标签多个标签用逗号分隔

分类