排错

本页按“现象 → 原因 → 解决办法”列出问题。找到和你看到的情况相符的条目即可。开始之前，请先弄清你是怎么运行 pi-webapp 的（Web 启动器、Pi 里的 /web，还是桌面应用），因为解决办法各不相同。

不要靠删除 ~/.pi 来“修复”任何问题：那里有你的会话和凭据。下面的步骤都不需要你分享令牌或 Key。

命令行提示是中文的

命令行启动器目前只输出中文。下面引用了原文，方便你搜索，并说明了含义。所有启动器消息都收在参考里。

启动与打开

浏览器没有打开，或者我把标签页关了

原因。 启动器只在本地图形会话里才会打开浏览器。通过 SSH、没有 DISPLAY 或 WAYLAND_DISPLAY 的 Linux、桌面应用内，或者设置了 PI_WEBAPP_AUTO_OPEN=0 时，它都不会尝试。无法打开时，它会提示 当前没有本地图形桌面，请手动打开上方地址。。

解决。 打印地址，然后在浏览器里打开：

npx pi-webapp status

pi-webapp 正在运行：http://127.0.0.1:52395/#<token>

在远程机器上，请转发端口，而不是把它暴露出去。

刚启动就显示 pi-webapp 未运行，或者第二天变成这样

原因。 服务停了：你运行了 pi-webapp stop、重启了电脑、注销了登录，或者 Pi 退出了。它不是系统服务，不会自己启动。

解决。 再运行一次 npx pi-webapp。它会得到新的端口和新的令牌，所以之前的书签不能用了。如果它是意外停止的，请看日志末尾。

页面能打开，但显示“打开 Pi 中 /web 给出的完整地址”

原因。 你打开的地址没带令牌，比如手动输入了 http://127.0.0.1:52395，漏掉了 #… 部分。提示里提到 /web，是因为同一个页面也用于 Pi 终端模式。

解决。 运行 npx pi-webapp status（或在 Pi 里输入 /web），打开完整的地址。

提示 访问令牌无效

原因。 页面里的令牌不是服务当前的令牌，通常是因为服务重启了，而你停留在旧标签页或旧书签上。

解决。 关掉旧标签页，打开 npx pi-webapp status 给出的当前地址。

页面显示 来源不匹配，或者实时更新收不到

原因。 你是通过一个和它打印的端口不同的转发或代理端口访问的。服务只接受来源恰好是那个地址的请求。

解决。 在你这一侧转发同一个端口号，例如 ssh -L 52395:127.0.0.1:52395 you@host，并按原样打开它打印的地址。不要把它放到另一个端口上的反向代理后面。

pi-webapp: 需要 Node.js 22.19 或更新版本。

原因。 你的 Node.js 比 22.19 旧。

解决。 用 node --version 检查，并从 nodejs.org 安装当前的 LTS。

Pi 版本 … 不受支持，需要 0.87.1 或更新版本

原因。 启动器退回去用了你 PATH 里的 Pi，而它太旧。这种情况出现在源码目录和较旧的包里；正常的 npm 包使用自己固定版本的 Pi。

解决。 用你习惯的方式更新 Pi，并用 pi --version 确认。启动器从不会替换你自己安装的 Pi。

Pi 启动超时 或 后台启动超时，后面跟着一个日志路径

原因。 Pi 在大约一分钟内没有报告就绪。常见原因是首次下载太慢、某个扩展出错，或者某个数据文件损坏。

解决。 阅读消息里指出的日志（位置），处理它报告的问题，然后重试。如果上一次启动还在关闭，请等一会儿再试。

找不到构建后的扩展。请先运行 npm run build。

原因。 你在运行的源码目录还没有构建。

解决。 在仓库里运行 npm ci 和 npm run build，再运行 npm run start。

服务能用，但我是在错误的目录里启动的

原因。 服务已经在运行时，在别的目录里再运行一次 npx pi-webapp 不会添加那个目录。

解决。 在侧栏里使用 添加工作区（会话与工作区）。

侧栏里少了一个工作区或会话

原因。 你把这个工作区从列表里移除了，或者它的会话存放在另一个 Pi 数据目录下（PI_CODING_AGENT_DIR）。里面什么都没有的会话只在打开时才会列出，而你删除过的会话在 pi-web/trash/ 里。

解决。 点 添加工作区，重新选择这个目录。如果你用了自定义数据目录，请看文件与目录。移除工作区从不会删除它的会话。要找回已删除的会话，把它的文件从 pi-web/trash/ 移回 sessions/ 下。

模型与回复

回复因为认证或网络错误而失败

原因。 Key 或登录缺失或已过期，模型名对该提供方无效，或者运行服务的机器连不上提供方。对话里的错误文字是 模型请求失败，或者提供方自己的信息。

解决。

1. 打开 Pi 设置 → 模型，点该提供方的 编辑，重新输入 Key 或重新登录。
2. 确认你选的模型对这个提供方确实存在。
3. 在公司代理后面？在启动服务的那个进程的环境里设置 HTTPS_PROXY（按需设置 HTTP_PROXY、NO_PROXY），再重启服务。ALL_PROXY 也会被读取。

“模型服务的使用额度已耗尽”

原因。 提供方的额度用完了。

解决。 切换到别的模型或提供方，或者等到额度重置。

“先选择模型，再开始对话”，而且模型列表是空的

原因。 还没有连接任何提供方，或者连接了但没有模型。

解决。 按模型与提供方操作。自定义提供方至少需要一个 模型 ID。

网页登录在提供方页面上已经完成，但 pi-webapp 没有反应

原因。 提供方的回调没能到达运行 Pi 的那台机器，这在远程或容器化的环境里很常见。

解决。 在登录卡片里展开 无法自动完成？手动输入授权码，粘贴授权码。不要把授权码粘贴进对话。

斜杠指令没反应，或者提示“运行中不执行斜杠指令，请等待当前回复结束”

原因。 斜杠指令只能在 Pi 空闲时运行，也不能排队。

解决。 等回复结束，或者先 暂停执行，再运行指令。

停止与更新

pi-webapp stop 被拒绝，因为有插件视图尚未保存

pi-webapp: 停止已取消：插件保存或释放未完成，服务及数据已保留。请先保存并关闭所有 pi-webapp 浏览器标签页，或在插件页处理未确认的视图后重试；开发时可运行 pi-webapp stop --force 强制停止（可能丢失未保存的编辑）。

原因。 某个插件视图（比如打开着的 Excalidraw 编辑器）还没有确认它的内容已保存。没有关闭编辑器就关掉浏览器，会让它停留在这个状态。

解决。 重新打开页面，保存并关闭那张图或那个编辑器，再运行一次 pi-webapp stop。如果那个视图已经彻底不在了，用插件恢复对话框决定保留还是丢弃它未确认的修改（保留恢复记录 或 丢弃此视图）。万不得已时：

npx pi-webapp stop --force

pi-webapp: 强制停止将跳过插件视图的保存确认，未保存的编辑可能丢失。
pi-webapp 已强制停止

--force 会跳过保存检查，所以未保存的编辑可能丢失。如果服务在五秒内没有响应，它还会直接结束后台进程及其子进程，并先打印 pi-webapp: 服务 5 秒内没有响应强制停止，正在直接结束后台进程及其子进程。。

停止超时。后台进程 PID：…

原因。 服务在大约 40 秒内没有完成关闭。

解决。 先查看日志了解原因，然后使用 pi-webapp stop --force。

更新之后页面一直没有回来

原因。 新版本没有及时启动，或者它启动了但启动器回退到了旧版本。可能会有提示说新版没有及时就绪，后台可能已经回退。

解决。

1. 运行 npx pi-webapp status。如果它打印了地址，就打开它，并在 Pi 设置 → 通用设置 里看一下运行的版本。
2. 如果它打印 未运行，先确认没有正在进行的工作，再用 npx pi-webapp 重新启动。
3. 如果一直失败，请阅读日志。不要为了“修好”它而删除 ~/.pi 或手动修改 pi-web/releases/。

更新被“插件视图尚未确认保存”中止

原因。 某个编辑器或图的视图在 15 秒内没有确认它的内容已保存，所以为了保护你的修改，版本切换被拒绝了。

解决。 保存并关闭图和编辑器。如果某个视图在刷新后失联了，请在 插件视图恢复 对话框里查看它的本地副本，选择保留或丢弃，然后重试。

工具

终端标签页不见了，或者它的进程没了

原因。 刷新页面会重置标签页。停止或重启服务会结束终端进程。浏览器断开超过五分钟，就会失去它的终端。

解决。 新开一个终端。重新运行任何东西之前，先检查旧命令已经改了什么。

终端提示默认 shell 不存在

原因。 SHELL（Windows 上是 COMSPEC）指向的程序不存在或不可执行。界面提示是“终端不可用：默认 shell 不存在或不可执行。请修正 SHELL（Windows 为 COMSPEC）后重启应用。”

解决。 在启动服务的环境里把它设成一个真实的 shell，然后重启服务。

终端提示数量已达上限

原因。 每个会话最多 8 个终端，整个服务最多 32 个。界面提示是“终端数量已达上限，请关闭不用的终端后重试。”

解决。 关掉不用的终端标签页。

Git 是灰的、“忙碌”或被阻止

原因。 共用这个工作树的某个会话正在运行，或者 Git 有锁文件、未解决的冲突、正在进行的操作，或者你想要的分支已在另一个工作树里被检出。也可能根本没有安装 Git。

解决。 等相关会话空闲后刷新。不要盲目删除锁文件或强行切换分支；请到终端里完成或中止那个 Git 操作。用 git --version 检查。

插件开关是禁用的，或者开关被拒绝

原因。 插件开关要求所有会话都处于空闲，而页面只显示已确认的状态。

解决。 等会话结束或先暂停它们，然后重试。官方插件必须先下载，开关才起作用。

下载 Excalidraw 插件失败

原因。 服务连不上 npm，或者没有可用的兼容版本。下载失败不会自动重试，你已有的版本也保持不变。

解决。 检查网络，再次点 下载（或 检查更新）。

文件预览是旧的

原因。 预览和列表不会自动刷新。

解决。 使用“文件”标签页里的刷新按钮。

桌面版

macOS 提示无法打开应用

原因。 测试版带 ad-hoc 签名，没有经过公证。

解决。 按桌面版 → macOS 里的检查步骤操作。如果校验和或 codesign 检查失败，请停下。永远不要关闭 Gatekeeper 或 SIP。

桌面应用显示的版本和设置里的不一样

原因。 它们是两样东西：外壳（pi → 关于 pi）和正在运行的 pi-webapp 包（Pi 设置 → 通用设置）。被复用的服务也可能比应用更旧。

解决。 见桌面版 → 更新。

收集信息，提交问题报告

启动器日志是第一个应该阅读（自己先读过之后）并附上的东西：

系统	路径
macOS、Linux	~/.pi/agent/pi-web/launcher.log
Windows	%USERPROFILE%\.pi\agent\pi-web\launcher.log

如果你设置了 PI_CODING_AGENT_DIR，它就在那个目录下的 pi-web/launcher.log。每一行是一个 JSON 事件，比如 launcher_ready、launcher_stop_requested 和 pi_process_exit（带 reason）。

提交 issue 时请附上：

• 你的操作系统和 CPU、Node.js 版本、pi-webapp 版本（Pi 设置 → 通用设置）或桌面构建号，以及你的运行方式；
• 准确的操作步骤、你期望的结果和实际发生的情况；
• 脱敏后的错误文字，必要时附上截图。

不要附上带令牌的完整地址、你认为私密的绝对路径、私密对话、附件、auth.json 和私钥。绝对不要上传整个数据目录。