故障排查
排查 Pi 时不要同时改模型、凭据、配置和 Extension。先建立一个最小可工作的基线,再逐层恢复项目能力。
五分钟诊断顺序
按顺序运行:
node --versionpi --versionpi --list-modelspi --no-session --no-approve --no-tools \ --no-context-files --no-extensions --no-skills \ --no-prompt-templates --system-prompt "" \ --append-system-prompt "" -p "只回复 OK"这四步分别验证:
- Node.js 是否满足
>=22.19.0。 - CLI 是否正确安装并进入
PATH。 - Pi 是否检测到供应商凭据,并能列出对应模型目录;实际请求仍需第 4 步验证。
- 不加载用户与项目上下文、扩展、技能或模板,也不向模型暴露工具时,模型链路是否正常;Pi 内置系统提示仍然存在。
如果第 4 步通过,问题通常在资源加载、工具或终端交互层,不要继续重装 Pi。注意:--no-approve 本身不会禁用上下文文件和用户级资源,--no-context-files 也不会屏蔽用户级 SYSTEM.md 与 APPEND_SYSTEM.md,所以最小基线需要上面的完整参数组合。
症状速查
| 症状 | 最可能原因 | 先检查 |
|---|---|---|
pi: command not found | npm 全局 bin 不在 PATH | npm 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 工具失败 | 没有可用 Bash | Git Bash / WSL 与官方 Windows 指南 |
| 图片、颜色或快捷键异常 | 终端能力或键位冲突 | /hotkeys、终端设置 |
安装与版本
Node.js 版本太旧
Pi 1.5.0 要求:
Node.js >= 22.19.0确认当前 shell 使用的版本:
node --versionwhich nodeWindows PowerShell:
node --versionGet-Command node安装新版本后,完全关闭并重新打开终端,避免版本管理器仍保留旧环境。
pi 不在 PATH
先检查全局安装:
npm list -g --depth=0 @earendil-works/pi-coding-agentnpm prefix -g重新安装:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent不要同时用 npm、pnpm、Bun 和 curl installer 安装多个全局副本。which pi 或 Get-Command pi 应只指向你准备使用的那个版本。
版本升级后 Extension 报类型或导出错误
先看:
pi --versionpi --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 未设置"fipi --list-models openai授权与用量说明以 OpenAI 官方文档为准;回调与端口行为见 Pi 1.5.0 OpenAI 登录实现。
没有可用模型
按顺序检查:
pi --list-modelspi 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 能加载,再逐项恢复:
- npm 依赖。
- 文件和网络访问。
- 事件处理器。
- 自定义工具。
- 后台资源。
/reload 后重复通知、重复监听或进程不退出,通常说明初始化或清理不是幂等的。完整生命周期见做出第一个 Pi Extension。
MCP、会话、上下文与工具
MCP 服务或工具不可用
- 在 Pi 中运行
/mcp,查看服务器状态、登录要求和工具暴露方式。 - 会话外运行
pi mcp list可测试配置,但会实际启动已启用的本地服务器或连接远端。 - 检查项目
.pi/mcp.json是否受信任,配置修改后执行/reload。 - 检查第三方扩展是否注册了同名
/mcp并替换内置实现;注意--no-mcp不会禁用该替代扩展。 - 对 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 --statgit 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 与工具输出中的业务数据。
- 会话导出中的源代码或图片。