pi 装起来不复杂，一条命令的事。唯一要先想清楚的是认证方式：用已有订阅，还是用 API Key。下面把装、认证、第一次对话一次走通。
核心概念：两种认证方式
pi 装好后要靠某个 LLM 服务商的凭证才能干活，认证有两条路，差别是这篇唯一要搞清楚的：
订阅登录（/login）｜API Key
用什么｜Claude Pro/Max、ChatGPT Plus/Pro 等订阅｜服务商发的 API Key
计费｜复杂（订阅额度 + 可能的额外用量）｜按 token，用多少花多少
凭证存哪｜~/.pi/agent/auth.json（OAuth token，自动刷新）｜环境变量 或 auth.json
适合谁｜已有订阅、不想单独管 Key｜想精确控费
提醒一句：Anthropic 订阅登录（Claude Pro/Max）走第三方 harness 通道，按 token 计费，不消耗订阅套餐额度，pi 会弹警告，正常现象。想完全可控、随时看花了多少，API Key 更省心。
动手实践
1. 装 pi
pi 跑在 Node.js 上，要求 22.19.0 或更高，先 node --version 确认。两种装法任选：
# npm 全局安装（--ignore-scripts 跳过依赖脚本，更安全）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 或用 curl 安装器（没装 Node 时它会帮你装）
curl -fsSL https://pi.dev/install.sh | sh装完 pi --version 验证。卸载都用 npm uninstall -g @earendil-works/pi-coding-agent。
2. 配认证
路线一：API Key（推荐），把 Key 设成环境变量：
export ANTHROPIC_API_KEY=sk-ant-...
pi或在 pi 里 /login 选一个 API Key provider，把 Key 存进 ~/.pi/agent/auth.json（0600 权限，只有自己能读写）。常用服务商的环境变量：
服务商｜环境变量
Anthropic｜ANTHROPIC_API_KEY
OpenAI｜OPENAI_API_KEY
DeepSeek｜DEEPSEEK_API_KEY
Google Gemini｜GEMINI_API_KEY
Groq｜GROQ_API_KEY
xAI｜XAI_API_KEY
OpenRouter｜OPENROUTER_API_KEY
完整列表几十家，看官方 Providers 文档[1]。
路线二：订阅登录，已有 Claude Pro、ChatGPT Plus 之类订阅的，pi 里 /login 选对应 provider，走一遍 OAuth，token 过期 pi 自动刷新。可选：Claude Pro/Max、ChatGPT Plus/Pro(Codex)、GitHub Copilot、xAI、OpenRouter。登出用 /logout。
Pi的社区很活跃，最新的Pi Agent已经支持了千问的token plan。
配置好模型止后就可以使用 /model 来选择自己想要使用的模型。
Pi Agent 还有一个 scoped models 的概念。
这个 scoped models 的目的是让用户可以在几个模型直接通过 ctrl + p 快速切换。也可以使用 ctrl + l 选择。对应的配置在 ~/.pi/agent/settings.json 文件的 enabledModels 字段
3. 第一次启动
进到项目目录启动：
cd /path/to/your/project
pi第一次进某个含 .pi/ 配置的项目，pi 会问信不信任--项目级资源可能含能执行任意代码的扩展，pi 不让你在不知情下加载。信任决定记在 ~/.pi/agent/trust.json，下次不再问。
界面从上到下四块：Header（快捷键/已加载资源）、Messages、Editor（你打字处，边框颜色=思考层级）、Footer（目录/会话/token 用量/花费/当前模型）。直接打字回车，比如：
帮我看看这个仓库的结构，告诉我怎么跑它的检查。pi 默认给模型四个工具：read、write、edit、bash。另外三个只读工具 grep/find/ls 默认关闭，需要时用 --tools 启用，比如让 pi 只读不写地做代码审查：
pi --tools read,grep,find,ls -p "审查这个仓库的代码质量"切模型按 Ctrl+L 或 /model；退出按两次 Ctrl+C 或 /quit；接着上次聊用 pi -c。
理解原理
认证解析顺序：同时配了环境变量、auth.json、命令行参数时，pi 按 命令行 --api-key > auth.json > 环境变量 > models.json 取用。临时换 Key 测试直接 pi --api-key xxx，不动配置文件。
项目信任是输入守卫，不是沙箱：它只在交互启动时弹窗，非交互模式（pi -p）默认走 ask，可用 -a/-na 覆盖。pi 默认无沙箱，模型拿到 bash 能执行任何命令，处理不可信仓库要靠容器隔离，那是后面安全篇的内容。
常见问题
Q：pi --version 报 command not found，但 npm 说装好了。
多半是 npm 全局 bin 目录不在 PATH。npm prefix -g 看路径加进 PATH，nvm 用户记得 nvm use。
Q：启动时报 Node 版本太低。
pi 要 Node 22.19.0+，用版本管理器（fnm/mise/nvm）升级，或用 curl 安装器帮你装。
Q：Claude Pro 登录后每次都弹额外用量警告。
Anthropic 订阅走第三方通道按 token 计费。想关，在 ~/.pi/agent/settings.json 加：
{ "warnings": { "anthropicExtraUsage":false } }Q：Shift+Enter 没法换行。
pi 用 Kitty 键盘协议识别修饰键。iTerm2、Kitty、Ghostty 不用配置就能用，VS Code 1.109.5+ 默认支持。Windows Terminal、WezTerm、Alacritty 要手动加一行配置转发按键，看终端配置文档[2]。
Q：想完全离线，不连 pi.dev 检查更新。PI_OFFLINE=1 关掉所有启动期网络操作，只想关版本检查用 PI_SKIP_VERSION_CHECK=1。
参考资料
• Pi 快速上手文档[3]
• Pi Providers 文档[1] - 全部 Provider、环境变量、云厂商配置
• Pi Custom Models 文档[4] - models.json 自定义 Provider
• Pi Settings 文档[5]
• Pi Terminal Setup[2] - 各终端按键配置
• Pi GitHub 仓库[6]
引用链接
[1] 官方 Providers 文档: https://pi.dev/docs/latest/providers[2] 终端配置文档: https://pi.dev/docs/latest/terminal-setup[3] Pi 快速上手文档: https://pi.dev/docs/latest/quickstart[4] Pi Custom Models 文档: https://pi.dev/docs/latest/models[5] Pi Settings 文档: https://pi.dev/docs/latest/settings[6] Pi GitHub 仓库: https://github.com/earendil-works/pi