常见问题排查

本章基于 pi v0.84.1。问题按发生阶段排列：从安装到日常使用。

---

安装篇

症状：npm install -g 失败，一堆红字

可能原因：

1. Node.js 版本太低——pi 0.84.x 需要 Node ≥ 22
2. 网络连不上 npm 官方源（中国大陆常见）
3. macOS/Linux 上缺少全局安装权限

解决方案：

第一步，检查 Node 版本：

node --version

低于 22 的话，用 nvm 切换：

nvm install 22
nvm use 22

如果没有 nvm，去 nodejs.org 下载 LTS 版本安装。

第二步，网络问题。中国大陆用户换淘宝镜像：

npm config set registry https://registry.npmmirror.com

然后重新安装：

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

第三步，权限问题。macOS/Linux 上如果报 EACCES，不要用 sudo——npm 全局安装不建议走 root。正确做法是设 npm 前缀到用户目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @earendil-works/pi-coding-agent

---

症状：安装成功但 pi 命令找不到

可能原因： npm 全局 bin 目录不在 PATH 里。

解决方案：

先看 npm 全局 bin 在哪：

npm root -g

把这个路径加到 PATH 里。macOS/Linux 上通常是 /usr/local/bin，Windows 上是 %APPDATA%\npm。

验证：

echo $PATH | grep $(npm root -g)
# 或者 Windows PowerShell：
$env:Path -split ';' | Select-String 'npm'

如果路径不在里面，手动追加到 shell 配置文件中。

---

认证篇

症状：/login 登录失败，OAuth 回调打不开

可能原因：

1. 在 SSH 远程连接里跑 /login，没有浏览器
2. 网络拦截了 OAuth 回调地址
3. 提供商订阅无效或欠费

解决方案：

SSH 远程环境里，/login 会打印一个 URL。复制这个 URL 到本机浏览器打开，完成授权后终端会自动收到凭证。

如果是网络问题——检查能不能访问提供商的认证服务器：

curl -I https://api.anthropic.com

如果超时，说明需要代理。先配好代理再 /login。

---

症状：API Key 设了但 pi 说 “not authenticated”

可能原因：

1. 环境变量设了但没生效——当前终端会话没加载
2. auth.json 里缓存的旧凭证覆盖了环境变量
3. API Key 格式有问题——多了空格、引号、换行

解决方案：

按以下顺序排查：

第一，确认环境变量的值对不对：

echo $ANTHROPIC_API_KEY
# Windows PowerShell：
echo $env:ANTHROPIC_API_KEY

如果输出为空，检查你的 .bashrc / .zshrc 有没有写对。注意别加引号——export KEY="sk-xxx" 带引号反而可能出错。

第二，检查 ~/.pi/agent/auth.json。这个文件保存了 /login 或之前手动输入的凭证，它的优先级高于环境变量。如果里面是旧的，删掉或用 /logout 清除。

第三，检查 API Key 格式。直接在 pi 启动时传入验证：

pi --api-key sk-ant-xxx --list-models

能列出来说明 key 本身没问题，是环境变量或配置没写对。列不出来说明 key 可能过期或者格式错了。

---

症状：模型列表里找不到某个模型

可能原因：

1. 模型目录过期了
2. API Key 没有那个模型的访问权限
3. 对于 GitHub Copilot 模型，没在 VS Code 的 Copilot Chat 里先启用

解决方案：

刷新模型目录：

pi update --models

然后查看完整列表：

pi --list-models

如果还是看不到，确认你的 API 账户有该模型的访问权限。去提供商的后台（如 Anthropic Console、OpenAI Platform）检查。

GitHub Copilot 用户：某些模型需要在 VS Code 的 Copilot Chat 设置里先启用，pi 里才会出现。

---

模型连接篇

症状：发送消息后一直转圈，或者报 “Failed to fetch” / “connection timeout”

可能原因：

1. 在中国大陆，API 直连被墙
2. 代理没配或配错了
3. 提供商的 API 服务宕机
4. DNS 解析问题

解决方案：

第一步，测一下网络连通性：

# Anthropic
curl -I https://api.anthropic.com

# OpenAI
curl -I https://api.openai.com

如果超时，说明需要代理。

第二步，配代理。两种方式二选一：

方式 A——settings.json（全局生效）：

{
  "httpProxy": "http://127.0.0.1:7890"
}

方式 B——环境变量（当前终端生效）：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
pi

第三步，检查 DNS。有时候 DNS 污染导致解析到错误的 IP。临时换 DNS：

# Linux / macOS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

或者在你代理软件的设置里开”DNS 远程解析”。

第四步，如果上面都没问题，可能是提供商挂了。去看状态页：status.anthropic.com 或 status.openai.com。

---

响应卡顿篇

症状：AI 回复明显变慢，或者回复到一半停住了

可能原因：

1. 上下文太大——会话里塞了太多文件，每次请求 token 数激增
2. 推理等级设太高
3. 提供商高峰期或限流
4. 系统提示词（AGENTS.md + skills 等）太长

解决方案：

先看状态栏的上下文占用。如果快满了，触发压缩：

/compact

或者直接用 /new 开新会话，轻装上阵。

降低推理等级——按 Shift+Tab 切换到 low 或 off，对于简单问题没必要用 deep think。

检查系统提示词大小：如果 ~/.pi/agent/AGENTS.md 和项目 AGENTS.md 都很长，精简一下。启动时的头部信息会显示加载了多少字符——如果上了万字，会有明显影响。

---

症状：上下文很大之后 AI 回复质量下降——忘事、重复、答非所问

可能原因： 上下文接近窗口上限，模型只能看到最近的对话，早期指令被”挤出去”了。

解决方案：

手动压缩：

/compact 重点关注前面的需求列表和数据库 schema 变更

带指令的压缩让 LLM 在生成摘要时特别关注你指定的方面。

如果压缩后仍然不够，/new 开新会话。把关键信息从旧会话复制过来丢给新会话当 prompt。

预防：控制单次会话的长度。一个会话不要从”脚手架搭建”一路聊到”部署上线”——拆成几个阶段，每个阶段用新会话。

---

Token 与费用篇

症状：Token 消耗飞快，账单比预期高

可能原因：

1. 推理等级太高——high 和 max 推理本身消耗大量 token
2. 工具调用过于频繁——每次 read 大文件、bash 跑长输出都在吃 token
3. 会话太长不压缩，prefix cache 命中率降低
4. 用了按 token 计费的昂贵模型

解决方案：

降低默认推理等级。在 settings.json 里设：

{
  "defaultThinkingLevel": "low"
}

需要深度推理时临时用 Shift+Tab 切高等级。

关掉不必要的工具。如果只是想让 pi 解释代码，不需要 bash 和 write：

pi --tools read,grep,find,ls -p "解释 src/auth.ts 的逻辑"

定期压缩和开新会话。状态栏会显示费用——如果你看到一次问答花了 $0.5+，说明上下文已经很大了。

---

Windows 专属问题

症状：Windows Terminal 里 Alt+Enter 没反应

可能原因： Windows Terminal 默认绑定了 Alt+Enter 为全屏切换，pi 收不到这个快捷键。

解决方案： 在 Windows Terminal 设置里删掉 Alt+Enter 的全屏绑定，或者改用 Ctrl+Enter 发多行输入。pi 的 Windows Terminal 配置参考：设置 → 操作 → 找到 toggleFullscreen，删掉或改成别的键。

---

症状：复制粘贴快捷键不对

可能原因： Windows 终端里 Ctrl+V 有时被终端本身拦截。

解决方案：

• 粘贴图片用 Alt+V 而非 Ctrl+V
• 复制回复：Ctrl+X
• 如果都不行，右键菜单里通常有粘贴选项

---

症状：安装后 pi 命令在 PowerShell 里找不到

可能原因： PowerShell 的执行策略或 PATH 没刷新。

解决方案：

检查 npm 全局路径是否在 PATH 里：

npm root -g

通常返回 C:\Users\你的用户名\AppData\Roaming\npm。把这个路径加到系统环境变量的 PATH 里，然后重启 PowerShell。

如果提示”无法加载文件，因为在此系统上禁止运行脚本”，改执行策略：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

---

界面显示篇

症状：界面颜色不对、文字重叠、对齐乱掉

可能原因：

1. 终端不支持 True Color
2. VS Code 内置终端对比度设置太激进
3. 终端字体不兼容

解决方案：

检查终端是否支持 True Color：

echo $COLORTERM

Windows Terminal 和 iTerm2 都支持。如果输出是空的，换个现代终端。

VS Code 里：设置 terminal.integrated.minimumContrastRatio 为 1。

字体问题：换用等宽字体，推荐 JetBrains Mono、Fira Code 或 Cascadia Code。

---

症状：终端里图片不显示

可能原因：

1. 终端不支持图片协议（iTerm2 的 imgcat、Kitty 的 icat 等）
2. terminal.showImages 被关了
3. Windows Terminal 目前不完全支持内联图片

解决方案：

检查配置：

{
  "terminal": {
    "showImages": true
  }
}

换用支持图片的终端：iTerm2（macOS）、Kitty（跨平台）、Ghostty（跨平台）。

Windows 用户如果图片显示不了，这是已知的终端限制。可以用 --mode fullscreen 尝试，或者等 Windows Terminal 更新图片协议支持。

---

会话篇

症状：找不到之前的会话

可能原因：

1. 没配 --name，会话名是自动编号的，不好辨认
2. sessionDir 被改过
3. 会话文件被误删或权限有问题

解决方案：

用 /resume 浏览列表——按时间排序，最近的排最上面。如果还是找不到，手动到目录里看：

ls ~/.pi/agent/sessions/

看看文件最近修改时间。如果文件在但 /resume 看不到，检查文件权限。

---

症状：会话文件好几个 GB

可能原因： 一个会话跑了太多轮，中间塞了很多大文件和大命令输出。

解决方案：

没办法压缩已有的会话文件体积。预防：定期 /new 开新会话，或者用 /export 导出成 HTML 然后删掉原文件。

---

代理调试篇

症状：配了代理但 pi 仍然连不上

可能原因：

1. 代理地址写错了
2. httpProxy 只配在项目配置文件里，但非交互模式没信任项目，没加载
3. 代理软件本身没正常运行

解决方案：

先验证代理是否工作：

curl -x http://127.0.0.1:7890 https://api.anthropic.com -I

如果 curl 能通但 pi 不通，把代理写到全局配置 ~/.pi/agent/settings.json 而非项目 .pi/settings.json——非交互模式可能没加载项目配置。

如果 curl 也不通，检查代理软件是否在运行、端口是否正确。

---

进阶：/debug 调试日志

pi 内置了一个隐藏的调试命令。在交互模式输入 /debug，会把以下内容写到 ~/.pi/agent/pi-debug.log：

• 渲染后的 TUI 行（带 ANSI 码）
• 最后发送给 LLM 的消息内容

如果上面所有排查都没解决你的问题，/debug 给出来的信息拿去提 Issue 或问社区，会大幅提高被解答的速度。

---

下一章是这本教程的终点站——整理所有学习资源，画一条从零到精通的路线图。