常见问题

先确定问题发生在启动、模型请求、项目操作还是远程连接，再查看对应步骤。保留具体错误信息，比反复重装更容易定位原因。

打不开 Pi Desk

确认服务正在运行，并使用它实际监听的地址。桌面默认地址为 http://127.0.0.1:30333/，直接运行 pi-desk 的默认地址为 http://127.0.0.1:6233/；自定义端口以当前配置为准。

桌面控制中心可“查看日志”。命令行方式检查终端是否已退出、Node.js 是否满足 22.19.0 或更新版本、端口是否被占用，以及当前 Node/npm 环境中是否有可用的全局 Pi。命令行不会自动安装 Pi；桌面端缺失 Pi 时需要接受安装确认。安装源访问失败与服务启动失败需要分别处理。

详见安装与启动。

npx 或 npm 安装 Pi Desk 会自动安装 Pi 吗

不会。npx @jetcrab/pi-desk 只下载或运行 Pi Desk，npm install -g @jetcrab/pi-desk 只全局安装 Pi Desk，都不会自动安装 Pi。缺少 Pi 时，启动提示会列出可直接复制的安装命令，并说明安装后如何重新启动。

提示中的国内镜像供中国用户加速下载，与官方源提供相同的 npm 包。桌面客户端会提供 Pi 安装入口，需要你确认后才安装。详细命令见通过 Node.js 安装。

Pi 无法加载或缺少 SDK 能力，怎么办

Pi Desk 不要求特定 Pi 版本，启动时检查 Pi 是否可加载、所需 SDK 能力是否存在。失败提示会保留具体原因，并给出安装或更新到最新 Pi 的命令。先停止 Pi Desk，在启动服务所用的 Node/npm 环境中执行命令，再重新启动服务。具体命令和供中国用户加速下载的镜像见更新 Pi 和 Pi Desk。

更新 Pi Desk、更新插件或“重载 Pi 配置”都不能代替更新 Pi 本体。如果已经更新仍报错，检查终端和桌面端是否使用了不同的 Node/npm 环境；桌面端可在安装选项中核对 Pi 的位置，再点击“重新检测”。

安装后为什么没有可用模型

Pi Desk 不包含模型额度。按照开始对话中的步骤连接自己的服务，再为会话选择可用模型。模型列表出现一个名字，也不代表账号已经获得该模型的使用权限。

回复成功，但执行命令失败

模型服务和项目命令运行在不同环节。检查运行 Pi Desk 的设备是否安装了所需程序、项目目录是否正确、该进程是否能访问目标文件。

手机能发送消息，并不代表命令会在手机上执行。不要为了修复某个项目依赖问题而反复更换模型。

手机能看到消息，为什么没有电脑上的草稿

访问同一服务、同一工作会话时，已发送消息、排队消息和当前模型双向同步；未发送文字与待发送图片属于各浏览器自己的草稿，不同步。当前主会话、焦点和滚动位置也各自保留。

如果发送结果显示未知，先检查聊天中是否已有该条消息，再决定“恢复草稿”或删除待确认内容，不要仅凭另一设备的输入框为空重复发送。详见多设备使用。

Fork 会不会撤销文件修改

不会。会话分支切换只改变聊天继续的位置；Fork 从用户消息之前的历史创建新会话，并回填该消息正文供你编辑后发送。源会话不变，项目文件仍是同一份，也不会自动创建 Git 分支。需要回退代码时使用项目的 Git 工具；需要独立文件环境时，先准备不同的项目目录。

为什么不能切换 Git 分支

先确认“项目文件”或输入区 Git 分支入口读取到了目标仓库。当前项目有运行中的 Agent 时，创建和切换分支被阻止，应停止相关任务或等待结束；即使聊天已空闲，未提交修改或无效分支名也可能让 Git 拒绝操作。界面会保留具体错误，不会自动丢弃文件修改。

“只看变更”里的 Diff 比较 HEAD 与工作区，不是单独的暂存区差异；二进制或超过 5MB 的文件不提供在线文本 Diff。

项目与会话保存在哪里

项目文件保存在选择的目录中，Pi 会话默认保存在服务设备的 Pi Agent 目录下，通常为 ~/.pi/agent/sessions/。自定义 Agent 或会话目录时，以当前启动配置为准。

模型请求会发送给你配置的模型服务。换浏览器访问同一个服务可以继续对话；启动另一套独立服务不等于复制了原服务的数据。

关闭网页会不会停止任务

关闭网页通常只是断开查看入口。任务是否继续由服务及对应插件的运行环境决定；停止服务、重载相关插件或退出桌面托管环境可能中断任务。

不要通过关页面代替停止操作。

插件已经安装，为什么还没有工具或界面

先到插件管理查看安装和加载结果。安装失败、界面加载失败与当前会话尚未加载新原生扩展，是不同情况。

外层界面更新不一定重载已经存在的 Pi 会话。需要时在目标会话空闲后使用“更多 → 重载 Pi 配置”，或者创建新会话验证。只有工具能力、没有界面入口的插件，本来就不会新增独立页面。

详见插件更新与加载。

手机访问不了，电脑却能打开

手机里的 127.0.0.1 指向手机自身，不是运行服务的电脑。应使用可达的局域网地址或已配置的公网访问地址。

按远程访问检查本机服务、桌面端隧道状态，以及服务器的 7001、7002 和访问端口是否放行。开放远程访问前必须设置访问密码。

忘记登录密码

如果你管理运行服务的设备，先停止公网隧道并关闭局域网访问，再移走实际 Pi Agent 目录中的 pi-desk/auth.json。登录保护会被解除，不需要重启服务。在本机刷新页面，进入「设置 → 登录保护」，设置并确认新密码。启用保护后，才恢复远程访问。

这是解除登录保护的操作。先关闭不需要的外部访问，确认自己操作的是目标服务的目录，再处理文件。不要删除整个 Pi Agent 目录，也不要把它与模型认证文件 auth.json 混淆：这里指的是 pi-desk/auth.json。

仅使用他人服务时，请联系服务管理者。

如何反馈问题

提供发生问题的页面或插件名称、操作步骤、版本信息、具体错误和必要截图。网页服务版本可在“设置 → 关于”查看。启动失败附相关启动日志；模型失败附错误类型；远程访问说明本机和外部设备分别能到哪一步。

模型密钥、登录密码和隧道控制密钥不是定位问题所必需的截图内容。