Pi Agent 见问题排查

以下是 Pi Agent 使用过程中的常见问题和解决方案。

---

安装问题

npm install 失败

可能原因和解决方案：

• Node.js 版本过低：Pi Agent 需要 Node.js 18+。使用 node --version 检查，用 nvm 切换版本
• 网络问题：在中国大陆可能需要设置 npm 镜像源。运行 npm config set registry https://registry.npmmirror.com
• 权限问题：macOS/Linux 上全局安装可能需要 sudo，或配置 npm 前缀到用户目录

安装后 pi 命令找不到

检查 npm 全局 bin 目录是否在 PATH 中：

$ npm bin -g
/usr/local/bin

$ echo $PATH | grep $(npm bin -g)

---

认证问题

/login 登录失败

• 确认你的订阅处于有效状态
• 检查网络连接，确保能访问提供商的认证服务器
• 如果在 SSH 远程连接上使用 /login，OAuth 回调可能需要手动粘贴 URL

API Key 不生效

检查以下顺序：

1. 环境变量是否正确设置（echo $ANTHROPIC_API_KEY）
2. auth.json 中的凭证是否覆盖了环境变量
3. API Key 格式是否正确（注意不要有多余空格或引号）

模型不可用

• 运行 pi update --models 刷新模型目录
• 运行 pi --list-models 查看可用模型列表
• 检查你的 API Key 是否有对应模型的访问权限
• GitHub Copilot 模型显示 "not supported"：需要在 VS Code Copilot Chat 中先启用该模型

---

界面问题

界面显示异常（颜色错误、对齐错乱）

• 确认终端支持 True Color：echo $COLORTERM
• 在 VS Code 中，设置 terminal.integrated.minimumContrastRatio 为 1
• 尝试更换终端（推荐 iTerm2 或 Windows Terminal）

图片无法显示

• 确认终端支持图片显示协议（iTerm2 的 imgcat、Kitty 的 icat 等）
• 检查 terminal.showImages 是否为 true

快捷键不生效

• 终端可能拦截了某些快捷键。检查终端设置中的快捷键绑定
• 运行 /hotkeys 查看当前所有快捷键绑定
• 使用 ~/.pi/agent/keybindings.json 自定义快捷键

---

会话问题

会话文件过大

• 使用 /compact 压缩对话历史
• 启用自动压缩：确保 compaction.enabled 为 true
• 定期用 /new 开始新会话

找不到之前的会话

• 使用 pi -r 或 /resume 浏览会话列表
• 检查 sessionDir 设置是否被修改
• 验证 ~/.pi/agent/sessions/ 目录权限

---

性能问题

AI 响应很慢

• 检查网络连接（ping api.anthropic.com 等）
• 尝试降低推理等级（Shift+Tab）
• 缩短系统提示词或减少 AGENTS.md 的内容
• 检查是否在使用高峰期

大量上下文后 AI 表现下降

• 手动触发 /compact 压缩上下文
• 使用 /new 开始新会话
• 减少不必要的上下文文件内容

---

代理设置

在中国大陆访问 API

在 settings.json 中配置 HTTP 代理：

或者设置环境变量后启动：

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