跳转到内容

故障排查

排查 Pi 时不要同时改模型、凭据、配置和 Extension。先建立一个最小可工作的基线,再逐层恢复项目能力。

五分钟诊断顺序

按顺序运行:

终端窗口
node --version
pi --version
pi --list-models
pi --no-session --no-approve --no-tools \
--no-context-files --no-extensions --no-skills \
--no-prompt-templates --system-prompt "" \
--append-system-prompt "" -p "只回复 OK"

这四步分别验证:

  1. Node.js 是否满足 >=22.19.0。
  2. CLI 是否正确安装并进入 PATH。
  3. Pi 是否检测到供应商凭据,并能列出对应模型目录;实际请求仍需第 4 步验证。
  4. 不加载用户与项目上下文、扩展、技能或模板,也不向模型暴露工具时,模型链路是否正常;Pi 内置系统提示仍然存在。

如果第 4 步通过,问题通常在资源加载、工具或终端交互层,不要继续重装 Pi。注意:--no-approve 本身不会禁用上下文文件和用户级资源,--no-context-files 也不会屏蔽用户级 SYSTEM.md 与 APPEND_SYSTEM.md,所以最小基线需要上面的完整参数组合。

症状速查

症状最可能原因先检查
pi: command not foundnpm 全局 bin 不在 PATHnpm prefix -g、重开终端
启动时报 Node 版本错误Node.js 太旧node --version
/model 没有可用模型凭据缺失或目录未刷新/login、pi --list-models
/model 列表太长,每次选模型都很慢尚未设置常用模型范围用 /scoped-models 从零勾选并保存
登录成功后仍认证失败启动进程没有读到凭据,或 OAuth 需刷新同一 shell 重试 /login
项目 Skill/Extension 不出现项目未受信任或未重载/trust、重启、/reload
非交互任务忽略项目配置Print/JSON/RPC 不弹信任提示显式 --approve
/reload 后 Extension 行为重复初始化不是幂等,后台资源未关闭session_shutdown
工具能看到却无法执行schema、权限、路径或运行模式错误工具错误结果与启动目录
上下文很快满大输出、重复文件或长会话/session、/compact
Windows shell 工具失败没有可用 BashGit Bash / WSL 与官方 Windows 指南
图片、颜色或快捷键异常终端能力或键位冲突/hotkeys、终端设置

安装与版本

Node.js 版本太旧

Pi 1.5.0 要求:

Node.js >= 22.19.0

确认当前 shell 使用的版本:

终端窗口
node --version
which node

Windows PowerShell:

终端窗口
node --version
Get-Command node

安装新版本后,完全关闭并重新打开终端,避免版本管理器仍保留旧环境。

pi 不在 PATH

先检查全局安装:

终端窗口
npm list -g --depth=0 @earendil-works/pi-coding-agent
npm prefix -g

重新安装:

终端窗口
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

不要同时用 npm、pnpm、Bun 和 curl installer 安装多个全局副本。which pi 或 Get-Command pi 应只指向你准备使用的那个版本。

版本升级后 Extension 报类型或导出错误

先看:

终端窗口
pi --version
pi --help

再对照 Pi changelog。常见破坏性变化包括:

  • coding-agent SDK 从旧 AuthStorage / ModelRegistry 选项迁移到异步 ModelRuntime。
  • 1.5 工具参数改为 pi-schema 校验;TypeBox 的 Type.Refine()、自定义格式和 codec 不再应用于工具参数。
  • Extension 事件或工具结果结构收紧。

先检查1.5 参数校验迁移,把业务约束放进工具执行逻辑,并测试非法输入和类型转换。

固定依赖版本,先在临时分支升级并运行 Extension 的失败路径。

认证与模型

OpenAI GPT:登录、额度与 provider 不匹配

本节以 Pi 1.5.0 为参考,步骤见接入 OpenAI GPT。先区分当前使用的是 openai 的 ChatGPT 登录、openai 的 API Key,还是旧的 openai-codex。

症状检查与处理
/login openai 中没有 Sign in with ChatGPT运行 pi --version;这条入口从 0.99.0 起提供。按原安装方式升级并重启,或在 0.83.0 中使用 openai-codex 的旧订阅入口
旧订阅登录成功,选择 openai 却提示缺少凭据openai-codex 与 openai 的凭据分别保存;重新执行 /login openai,再用 /model 选择 openai 模型
设置 OPENAI_API_KEY 后仍使用 ChatGPT 订阅已保存的凭据优先;用 /logout 选择 OpenAI,再从注入 Key 的 shell 重启 Pi
只登录了账号,仍不能使用计划重新执行 /login openai,检查是否允许 Use your ChatGPT plan,以及账号是否符合资格
提示计划额度耗尽或达到使用上限检查 ChatGPT 的 Settings → Usage 与应用限额;Pi 与已有计划共享用量。API Key 路径则检查 OpenAI Platform 项目的 API 额度与速率限制
提示模型不可用或无权访问检查模型所属 provider;运行 pi update --models 并重新选择账号可用模型。目录条目不代表账号已获得权限
Port 1455 is in use 或浏览器提示 OAuth state mismatch取消其他 Pi 会话或 Codex CLI 中尚未完成的登录,再重新执行 /login openai;不要同时进行多个回调登录
SSH 中浏览器无法完成回调按 Pi 提示粘贴浏览器的完整最终回调 URL;新版 openai 流程不能只粘贴授权码

不输出密钥地检查环境变量是否已注入:

终端窗口
if test -n "$OPENAI_API_KEY"; then
echo "OPENAI_API_KEY 已设置"
else
echo "OPENAI_API_KEY 未设置"
fi
pi --list-models openai

授权与用量说明以 OpenAI 官方文档为准;回调与端口行为见 Pi 1.5.0 OpenAI 登录实现。

没有可用模型

按顺序检查:

终端窗口
pi --list-models
pi update --models

然后进入交互模式:

/login
/model

不要从网上复制一个模型 ID 直接猜。pi --list-models 和 /model 可以确认 Pi 当前识别的模型;是否有权限调用,仍需实际请求验证。详见模型目录与账号权限。

环境变量明明设置了,Pi 却看不到

确认变量和 Pi 在同一个进程环境中:

终端窗口
test -n "$ANTHROPIC_API_KEY" && echo "set" || echo "missing"
pi --list-models anthropic

只检查是否存在,不要打印真实值。图形化 IDE、终端 multiplexer、容器和 CI runner 可能不会继承你刚修改的 shell 配置。

SSH 或无头环境无法完成登录

Pi 的部分供应商支持设备码、粘贴回调地址或授权码。1.5 的部分设备码登录在按 Enter 后可打开验证页面并复制代码。按照 /login 当时显示的流程操作,不要假设所有供应商都使用同一种 OAuth 回调。

如果自动打开浏览器失败,把提示中的授权链接复制到另一台有浏览器的设备。详细流程以 Providers 为准。

调试外部客户端凭据

先用不打印凭据的状态检查:

终端窗口
pi auth check --provider "<provider>"

需要向受控进程输出凭据时还有:

终端窗口
pi auth print-api-key --provider "<provider>" --model "<model>"
pi auth print-bearer-token --provider "<provider>" --model "<model>"

这些命令会把真实凭据写到 stdout,只适合受控的进程间集成。不要粘贴到终端日志、聊天、Issue、CI 输出或文档。一般排错优先使用 /login 和 pi --list-models,不需要打印秘密。

项目信任与资源加载

项目设置、Skill 或 Extension 没加载

交互模式中:

/trust

保存信任后重启 Pi。/trust 写入未来会话的决策,不会自动重新启动当前会话。

之后执行:

/reload

检查启动头部是否列出了目标资源,以及是否存在加载诊断。

项目信任控制 .pi/settings.json、.pi 资源、项目 .agents/skills 和项目 Package。它不限制 Pi 对文件或 shell 的系统权限。

Print、JSON 或 RPC 模式行为与交互模式不同

非交互模式不显示项目信任提示。选择一种明确策略:

终端窗口
# 已审查并需要项目资源
pi -p --approve "运行项目定义的检查"
# 不需要项目资源
pi -p --no-approve "只概览公开文件"

不要依赖之前某次交互提示的记忆。自动化脚本应在命令中表达边界。

AGENTS.md 在未信任项目中仍然生效

这是预期行为。AGENTS.md 和 CLAUDE.md 属于上下文文件,默认会加载,不受项目信任开关保护。

需要完全忽略上下文文件时使用:

终端窗口
pi --no-context-files

不可信仓库中的文档、注释、构建输出和上下文文件都可能包含提示注入。真正的安全边界仍然是容器、VM 或策略沙箱。

Skill 与 Extension

Skill 没有被发现

检查:

  • SKILL.md 是否在目录中。
  • frontmatter 是否有非空 description;省略 name 时 Pi 使用父目录名。
  • name 是否符合可移植的命名规则;格式问题通常产生警告。
  • 是否发生同名冲突。
  • 项目是否受信任并执行过 /reload。

显式测试可以绕开自动发现:

终端窗口
pi --skill ./path/to/skill

完整步骤见做出第一个 Pi Skill。

Extension 加载失败

用显式路径隔离问题:

终端窗口
pi -e ./path/to/extension.ts

先移除第三方依赖和复杂初始化,缩减到只注册一个命令。如果最小 Extension 能加载,再逐项恢复:

  1. npm 依赖。
  2. 文件和网络访问。
  3. 事件处理器。
  4. 自定义工具。
  5. 后台资源。

/reload 后重复通知、重复监听或进程不退出,通常说明初始化或清理不是幂等的。完整生命周期见做出第一个 Pi Extension。

MCP、会话、上下文与工具

MCP 服务或工具不可用

  1. 在 Pi 中运行 /mcp,查看服务器状态、登录要求和工具暴露方式。
  2. 会话外运行 pi mcp list 可测试配置,但会实际启动已启用的本地服务器或连接远端。
  3. 检查项目 .pi/mcp.json 是否受信任,配置修改后执行 /reload。
  4. 检查第三方扩展是否注册了同名 /mcp 并替换内置实现;注意 --no-mcp 不会禁用该替代扩展。
  5. 对 1.5 的 OAuth 兼容性问题,检查 auto、dcr 和 cimd 的服务端支持,不要泄露回调或 token。

完整步骤见 MCP。

扩展更新了却没有更新日志

只加载 Skill、模板或主题的包不会显示;第一次看到扩展包只记录版本;更新后要全新启动,且 Git 包的 package.json 版本必须增加。/changelog 不展示扩展包日志。见扩展包更新日志。

上下文快满了

先执行:

/session

查看消息、token 和成本,再选择:

  • 用 /compact 总结旧上下文。
  • 用 /tree 回到更早节点。
  • 用 /fork 或 /clone 分离新方向。
  • 开新会话,把稳定结论写进文件而不是长期留在聊天里。

大段 shell 输出、生成文件和重复读取最容易消耗上下文。!!command 会执行命令但不把输出加入模型上下文。

工具输出被截断

这是保护上下文的预期行为。改用更窄的命令:

终端窗口
rg -n "target" src/
git diff --stat
git diff -- path/to/file

不要为了得到完整日志而无限提高输出上限。先筛选,再读取相关片段。

Agent 停止后仍有排队消息

在交互模式中:

  • Enter 发送 steering。
  • Alt+Enter 发送 follow-up。
  • Escape 中止并把排队消息恢复到编辑器。
  • Alt+Up 取回队列中的消息。

如果行为不符合预期,打开 /settings 检查 steeringMode 和 followUpMode。

网络与离线

关闭 Pi 的自动网络活动,包括模型目录自动刷新:

终端窗口
PI_OFFLINE=1 pi

它会关闭版本检查、Package 更新检查、安装/更新遥测和模型目录网络刷新。它不是网络防火墙,不能保证模型请求、MCP 服务或工具不会访问网络;离线模式也不提供尚未缓存的资源。需要硬隔离时在系统或容器层限制网络。

只关闭版本检查:

终端窗口
PI_SKIP_VERSION_CHECK=1 pi

只关闭安装/更新遥测:

终端窗口
PI_TELEMETRY=0 pi

这三个开关作用不同。不要用 PI_TELEMETRY=0 期待完全离线。

终端与平台

Windows shell 命令失败

Pi 的 shell 工具需要 Bash。常见选择:

  • Git for Windows 提供的 Git Bash。
  • WSL 中完整运行 Pi。

查看 Pi Windows 官方指南,确认路径、引号和终端快捷键。

思考级别和边框颜色不一致

先用 /thinking 看当前模型实际支持的档位;Shift+Tab 只循环可用档位。边框颜色由主题和终端决定,自定义主题可能让 max 与 xhigh 相同。详见模型、思考与主题。

Alt+Enter、粘贴或图片显示异常

  • 运行 /hotkeys 查看 Pi 当前键位。
  • Windows Terminal 的 Alt+Enter 默认可能切换全屏,需要重新映射。
  • Windows 粘贴图片常用 Alt+V。
  • 图片显示能力取决于终端支持的图形协议。

终端差异见 Terminal setup。

提交问题前收集最小证据

不要上传会话或整个配置目录。先准备:

Pi 版本:
Node.js 版本:
操作系统与终端:
启动命令(移除密钥):
最小复现步骤:
实际结果:
预期结果:
是否在 --no-session --no-approve --no-tools 下复现:

分享日志前删除:

  • API Key、Bearer Token 和 OAuth 回调。
  • 用户目录、私有仓库名和内部域名。
  • prompt 与工具输出中的业务数据。
  • 会话导出中的源代码或图片。

仍无法定位时,查看Pi 官方文档、现有 Issues,或按仓库要求提供最小复现。