Pi Agent 安装配置教程:安装、模型配置与扩展推荐

Pi Agent 的上手门槛不高，最容易卡住的其实只有两处：运行环境没有配好，或者模型没有真正接通。把这两步走通以后，网页访问、子 Agent 和长期记忆等都可以按需要加装。

Pi 是运行在终端里的编程智能体，负责把模型接入本地项目，读写文件、执行命令和管理上下文。它的本体很轻，实际使用哪个模型、安装哪些扩展，都由你决定。

一、运行环境准备

Pi 当前要求Node.js 22.19.0 或更高版本。先在终端运行下面两条命令：

node -vnpm -v

如果终端提示命令不存在，先安装新版 Node.js。Windows 还要多准备一个 Bash 环境。大多数人安装Git for Windows就够了，Pi 会自动找到其中的 Git Bash。

二、安装 Pi

Windows

打开 PowerShell，执行：

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

--ignore-scripts 会关闭依赖包的生命周期脚本。Pi 的常规 npm 安装用不到它们，可以少执行一些不必要的安装代码。

如果安装成功后仍提示找不到 pi，先关闭并重新打开终端，再检查 npm 的全局安装目录是否已经加入 PATH。

macOS

打开“终端”，运行官方安装脚本：

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

脚本会检查 Node.js 和 npm，版本不够时会询问是否帮你安装。Node.js 已经配好的话，也可以直接使用前面的 npm 命令。

Linux

在终端执行：

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

Ubuntu、Debian、Fedora 等常见发行版都可以这样安装。无交互的服务器环境需要先自行装好 Node.js 22.19.0 以上版本和 npm。

装好以后，进入项目目录并启动 Pi：

cd /path/to/your-projectpi

Pi 会把当前目录当作工作区，可以在这里执行命令或修改文件。正式使用前最好先做一次 Git 提交，方便随时回退。第一次启动时，可以输入“阅读这个项目并告诉我如何运行测试”，确认 Pi 能正常读取目录并回答。

三、登录官方支持的模型服务

进入 Pi，输入：

/login

从列表中选择服务商，再按浏览器或终端提示完成授权。Pi 目前支持 ChatGPT Plus/Pro（Codex）、Claude Pro/Max、GitHub Copilot、xAI、OpenRouter 和 Radius 等订阅登录，具体权限和计费仍以各服务商的页面说明为准。

登录成功后输入 /model，也可以按 Ctrl+L 打开模型选择器。退出账号使用 /logout。API Key 类型的服务商也能从 /login 录入，或者改用环境变量。凭据保存在用户目录下的 ~/.pi/agent/auth.json，不要把这个文件上传、分享或提交到代码仓库。

如果模型没有出现在 /model 中，先确认授权是否成功，以及账号是否真的拥有该模型。即使名称已经出现在列表里，也只能说明配置被读到了。最好再发一条真实消息，能正常返回才算接通。

四、第三方模型交给 CC Switch 管理

第三方 API 往往要填写端点、协议和模型 ID，直接手写 models.json 很容易漏字段。截至本文发布时，CC Switch v3.20.0已经把 Pi 纳入管理，可以用图形界面维护 ~/.pi/agent/models.json。预设、API 格式、模型能力和思考等级都能直接填写，特殊配置仍可切到原始 JSON 编辑。

配置时按下面几步操作：

安装或升级到 CC Switch v3.20.0，在顶部应用列表里选择 Pi。
添加供应商。有现成预设就直接选，没有再用自定义配置。
参照服务商文档填写 Base URL、API 格式、模型 ID 和 API Key，尤其要确认接口使用 Responses、Chat Completions、Anthropic Messages 还是 Gemini 协议。
保存并启用，回到 Pi 的 /model 选择新模型，再发送一条真实请求。

CC Switch 首次接入 Pi 时会导入 models.json 里的现有供应商，但它不读写 auth.json，也不替你设置默认供应商和默认模型。官方账号仍然在 Pi 里用 /login 登录，CC Switch 主要处理第三方和自定义 API。

有些服务商支持自动拉取模型列表，但这只能证明 API Key 和目录接口可用。Base URL、协议或参数不兼容时，对话依旧可能报错，最终还得看实际生成请求。配置文件也可能含有敏感信息，不要公开截图或提交到仓库。

五、分享 4 款扩展

安装命令很简单：

pi install npm:pi-web-accesspi install npm:pi-subagentspi install npm:pi-observational-memorypi install npm:@ff-labs/pi-fff

这些命令默认安装到当前用户。如果扩展只服务于某个仓库，在命令中加入 -l 即可，例如 pi install -l npm:pi-web-access，配置会写进项目的 .pi/settings.json。

1.pi-web-access

这是四款里最通用的一款。它给 Pi 补上网页搜索、URL 内容提取、PDF 解析、GitHub 仓库克隆，以及 YouTube 和本地视频理解。默认就有免 Key 的搜索通道，也能接入多家搜索服务。查官方文档、追版本更新或整理资料时都会用得上。

2.pi-subagents

任务一复杂，单个 Agent 就容易顾此失彼。pi-subagents 可以把代码侦察、资料研究、实现和复核分给不同的子 Agent，也支持并行和后台执行。代价是调用次数与费用都会增加，所以任务边界要写清楚，小改动没必要硬上多 Agent。

3.pi-observational-memory

如果一个会话要持续几天，这款扩展更有价值。它会提炼“观察”和“反思”，提前准备上下文压缩所需的记忆，重要决定不容易在多次压缩后丢失，等待时间也会缩短。当前 V3 不兼容 V2 的记忆和设置，老用户升级后要更新配置，并从新会话开始。

4.@ff-labs/pi-fff

仓库越大，文件搜索越影响体验。pi-fff 使用 Rust 原生的 FFF 搜索引擎，支持模糊匹配、预索引、Git 状态加权、使用频率排序和多关键词检索。它还能改进 @ 文件补全，让 Pi 更快把注意力放到相关文件上。

六、扩展管理与安全建议

Pi 扩展以当前用户权限运行，可以读写文件和执行程序。安装前应确认来源，至少看一遍项目说明、源码入口和权限提示。一次只加一个扩展，确认没有异常后再装下一个，重要项目则保留 Git 提交或其他可回滚快照。

扩展不必一口气全部装上。先用一个模型把 Pi 跑通，缺网页能力就加 pi-web-access，大型仓库可以再装 pi-fff。会话确实要跑很久时再考虑记忆扩展，需要分工或交叉复核时再启用 pi-subagents。这样更容易看清每个扩展到底带来了什么，也方便排查问题。