Pi Agent 常见问题排查
以下是 Pi Agent 使用过程中的常见问题和解决方案。
安装问题
本节覆盖安装阶段的典型报错与处理路径。
npm install 失败
现象：执行安装命令后中途报错退出，常见报错集中在版本、网络和权限三类。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| Node.js 版本过低，Pi Agent 要求 Node.js 22.19.0 或更高 | 执行 node --version 查看当前版本 | 用 nvm 安装并切换到 22 LTS 或更高版本 |
| 网络问题，国内访问 npm 官方源容易超时 | 观察报错中是否出现 ETIMEDOUT 等网络超时信息 | 执行 npm config set registry https://registry.npmmirror.com 切换镜像源后重装 |
| 权限问题，macOS/Linux 的全局安装目录当前用户不可写 | 观察报错中是否出现 EACCES 权限错误 | 用 nvm 管理 Node.js，或把 npm 前缀配置到用户目录，避免使用 sudo |
安装后 pi 命令找不到
现象：安装提示成功，但输入 pi 提示 command not found。
先查看 npm 的全局安装前缀：
$ npm prefix -g /usr/local
再确认该前缀下的 bin 目录是否在 PATH 中：
$ echo $PATH | grep "$(npm prefix -g)/bin" /usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin
目录不在 PATH 中时，这条命令没有任何输出：
$ echo $PATH | grep "$(npm prefix -g)/bin"
没有任何输出就说明全局 bin 目录不在 PATH 里，这就是找不到 pi 命令的原因。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 全局 bin 目录未加入 PATH | 用上面的 grep 命令确认是否有输出 | 把 $(npm prefix -g)/bin 追加到 ~/.zshrc 或 ~/.bashrc 的 PATH 中，重开终端生效 |
| 切换过 Node 版本，旧的软链接失效 | 执行 ls $(npm prefix -g)/bin 查看是否还有 pi | 在当前 Node 版本下重新执行一次全局安装 |
认证问题
本节覆盖 /login 登录与 API Key 认证失败的处理路径。
/login 登录失败
表现为输入 /login 后浏览器无法完成跳转，或界面一直停留在等待授权的状态。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 订阅不在有效状态 | 登录提供商官网确认订阅是否过期 | 续费订阅，或改用其他提供商登录 |
| 无法访问提供商的认证服务器 | 在浏览器中打开提供商站点确认网络可达 | 配置代理后重试，配置方式见下文代理设置一节 |
| 在 SSH 远程连接上使用 /login | 远程机器上没有浏览器，OAuth 回调无法送达 | 把授权 URL 复制到本地浏览器打开，再手动粘贴回调 URL 完成登录 |
API Key 不生效
现象：已经 export 了环境变量，启动时仍然提示未认证，或继续使用旧的凭证。
按以下顺序检查：
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 环境变量没有正确设置 | 执行 echo $ANTHROPIC_API_KEY 查看输出 | 输出为空时在 shell 配置文件中补上 export，再重新 source |
| auth.json 中已有同名凭证，优先级高于环境变量 | 查看 ~/.pi/agent/auth.json 中是否已存在该提供商的条目 | 执行 /logout 清除旧凭证，或直接编辑 auth.json 更新 Key |
| API Key 格式不正确 | 检查复制的内容中是否混入了多余空格或引号 | 重新完整复制一次 Key 再配置 |
auth.json 中已保存的凭证优先级高于环境变量。
API Key 不生效时先检查 ~/.pi/agent/auth.json，不要只盯着环境变量。
模型不可用
现象：模型列表里找不到预期的模型，或调用时提示没有权限。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 本地模型目录过期 | 执行 pi update --models 刷新模型目录 | 刷新完成后重新打开模型选择器 |
| 不清楚当前可用模型 | 执行 pi --list-models 查看可用模型列表 | 从列表中选择当前账号可用的模型 |
| API Key 没有对应模型的访问权限 | 在提供商控制台确认该 Key 的模型授权范围 | 升级套餐，或改用已授权的模型 |
| GitHub Copilot 模型显示 "not supported" | 确认是否已在 VS Code 中启用该模型 | 先在 VS Code Copilot Chat 中启用该模型，再回到 Pi Agent 使用 |
界面问题
本节覆盖终端渲染、图片显示与快捷键三类界面异常。
界面显示异常（颜色错误、对齐错乱）
现象：颜色发暗或失真，表格与文本框的边框错位。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 终端不支持 True Color | 执行 echo $COLORTERM，输出 truecolor 或 24bit 表示支持 | 换用支持 True Color 的终端（iTerm2、Windows Terminal 等） |
| VS Code 自动调整了终端对比度 | 检查设置项 terminal.integrated.minimumContrastRatio | 把该项设置为 1 |
| 当前终端的渲染兼容性差 | 换一个终端运行，确认问题是否复现 | 更换终端，推荐 iTerm2 或 Windows Terminal |
图片无法显示
现象：发送或粘贴图片后终端中只看到占位符或空白。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 终端不支持图片显示协议 | 确认终端是否支持 iTerm2 的 imgcat 或 Kitty 的 icat | 换用支持图片协议的终端 |
| 图片显示被配置关闭 | 检查 terminal.showImages 是否为 true | 改为 true 后执行 /reload 使配置生效 |
快捷键不生效
现象：按下文档中描述的快捷键没有任何反应，或触发了终端自身的功能。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 终端拦截了该快捷键 | 检查终端设置中的快捷键绑定列表 | 修改或释放终端中冲突的绑定 |
| 记错了当前的快捷键 | 执行 /hotkeys 查看当前所有快捷键绑定 | 按列表中的实际绑定操作 |
| 需要按个人习惯调整 | 确认配置文件 ~/.pi/agent/keybindings.json 是否存在 | 编辑该文件自定义快捷键 |
会话问题
本节覆盖会话文件膨胀与找不到历史会话两类问题。
会话文件过大
现象：上下文占用持续走高，响应变慢或提前触发压缩。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 对话历史过长 | 执行 /session 查看消息数与 token 用量 | 执行 /compact 压缩对话历史 |
| 自动压缩没有开启 | 检查 compaction.enabled 是否为 true | 设为 true 后重启 pi 生效 |
| 单个会话累积时间过长 | 用 /session 观察会话文件大小增长 | 定期用 /new 开始新会话，按任务拆分会话 |
找不到之前的会话
现象：pi -r 的列表里看不到之前的工作记录。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 没有使用恢复入口 | 执行 pi -r 或在交互模式输入 /resume 浏览会话列表 | 在列表中选中目标会话恢复 |
| sessionDir 设置被修改 | 检查 settings.json 中 sessionDir 的当前值 | 改回原目录，或把原目录下的文件迁移到新目录 |
| 会话目录权限异常 | 执行 ls ~/.pi/agent/sessions/ 确认可读写 | 执行 chmod -R u+rw ~/.pi/agent/sessions 修复权限 |
性能问题
本节覆盖响应慢与长上下文下表现下降两类性能问题。
AI 响应很慢
现象：提交请求后长时间没有首字输出，或整体耗时明显高于平时。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 网络延迟高或链路不通 | 执行 ping api.anthropic.com 查看延迟与丢包 | 切换网络，或按下文代理设置配置代理 |
| 推理等级过高，思考时间被拉长 | 观察状态栏当前的推理等级 | 按 Shift+Tab 降低推理等级 |
| 系统提示词或上下文文件内容过多 | 检查 AGENTS.md 等上下文文件的体积 | 缩短系统提示词，精简 AGENTS.md 的内容 |
| 单次请求的 token 消耗过大 | 执行 /session 查看 token 用量与耗时分布 | 执行 /compact 或 /new 缩短上下文后再试 |
若走代理环境，改用 curl -x $HTTP_PROXY https://api.anthropic.com 测试。
代理环境下 ping 不通不代表 API 不可用。
ping 走的是 ICMP，API 走的是 HTTPS，此时应改用 curl 验证真实链路。
大量上下文后 AI 表现下降
现象：对话轮次变多后 AI 开始遗忘此前的约定，或给出重复的答案。
| 可能原因 | 排查方法 | 解决方案 |
|---|---|---|
| 上下文接近窗口上限，早期内容被压缩掉 | 执行 /session 查看当前 token 用量 | 手动执行 /compact 压缩上下文 |
| 历史消息中混入了大量无效尝试 | 用 /tree 查看分支与无效对话 | 用 /new 开始新会话，把结论写进 AGENTS.md |
| 引用的文件内容与当前任务无关 | 检查 @ 引用与上下文文件中是否带了无关内容 | 减少不必要的上下文文件内容，只保留当前任务需要的部分 |
代理设置
本节说明在受限网络环境下如何让 Pi Agent 正常访问 API。
在国内访问 API
在 settings.json 中配置 HTTP 代理：
{
"httpProxy": "http://127.0.0.1:7890"
}
或者设置环境变量后启动：
$ export HTTP_PROXY=http://127.0.0.1:7890 $ export HTTPS_PROXY=http://127.0.0.1:7890 $ pi