Pi Bot 常见问题

查找 Pi Bot 安装、模型与 API Key、Ollama、工具审批、定时任务和 Android 配对的常见问题,按故障现象找到检查步骤与对应教程。

关于 Pi Bot

Pi Bot 是什么?

Pi Bot 是一款在自己电脑上运行的多 Agent 协作桌面应用,支持 macOS、Windows 和 Linux。你可以让多个 Bot 在同一个群里分工,处理文件、审查代码改动和运行例行任务。桌面版可以独立使用,Android 手机和执行端按需配对。参见下载 Pi Bot和多 Bot 群聊与任务交接。

Pi Bot 可以完全离线使用吗?

可以在本机配置 Ollama,让模型请求留在电脑上。依赖互联网的功能,如联网搜索和连接外部应用,仍然需要网络。参见配置 Ollama 和本地模型和了解数据去向。

下载与安装

我该下载哪个版本?

在下载页按设备选择安装包。Mac 上可在苹果菜单「关于本机」查看是 Apple 芯片还是 Intel。Windows 选 EXE,Linux 选 AppImage,Android 手机版选 APK。另一台电脑只负责执行时,下载「执行端」。

macOS 说无法验证 Pi Bot,怎么办?

官网的 macOS v0.0.1 尚未经过 Apple 公证。如果确认安装包来自官网并决定继续,请先尝试打开,再到「系统设置 → 隐私与安全性」点「仍要打开」。参见下载页的安装说明。

第一次打开需要配置什么?

至少需要一个可用的模型。欢迎流程提供 OpenRouter、ChatGPT 计划、本机 Ollama 和自带 API Key。参见安装与第一次使用和模型连接排查。

模型与密钥

「保存并测试」失败,提示 Key 无效。

检查 Key 是否完整复制(没有多余空格)、是否属于这个厂商、账户里是否还有余额或额度。厂商控制台里新建的 Key 有时要等一会儿才生效。换了 Key 后重新粘贴并「保存并测试」。

连不上模型厂商。

如果你的网络需要代理,在 设置 › 通用 › 网络代理 里打开「使用代理」,填地址后点「测试连接」。Pi Bot 不读系统代理。

ChatGPT 计划提示「已达用量上限」。

计划额度暂时用完了。可以在 ChatGPT 里管理用量,或在 设置 › 模型与密钥 › OpenAI 保存一个 API Key,再把 Bot 的模型改成「OpenAI」组下的模型。

工作收据里花费显示「未知」。

有些厂商或自定义网关不提供价格信息,Pi Bot 就不估算,只显示有几次请求没有定价。

文件夹与命令

Bot 说读不到 / 写不了某个文件夹。

Bot 默认只在话题的工作文件夹里读写。工作位置外的文件会先问你;要长期使用,在聊天顶部的文件夹菜单里把它设为主文件夹、「添加可写文件夹…」或「添加只读参考…」(见 4 · 工作文件夹与改动)。只读参考里的文件不能改。

Bot 跑不了命令。

按顺序检查:

  1. 设置 › 权限(或这个 Bot 的「权限」标签)里「运行命令」是不是「不允许」。
  2. 聊天里是否有一张没处理的审批卡(侧栏「待办」有数字)。
  3. Linux:是否装了 bubblewrap 和 socat。缺少时 Bot 会给出安装命令,装完后重试。
  4. 命令被沙箱拦下:Bot 会说明原因,可以请你确认「在沙箱外运行一次」;如果你打开了「严格沙箱」,就不会提供这个选项。
  5. Windows:每条命令都需要你批准,不能设成「总是允许」,这是因为 Windows 暂不支持命令隔离。
本地预览服务打不开。

Bot 启动的后台命令只能监听本机 127.0.0.1。从后台命令卡片上的「在 Bot 浏览器打开」打开,或在你自己的浏览器里访问卡片上的地址。

审批

审批卡显示已过期。

聊天里的审批 10 分钟内没处理,任务会暂停等你;例行任务的审批 24 小时内没处理会自动拒绝。重新发消息让 Bot 继续,或在例行任务里「立即运行」。

点了「一直允许」,想撤回。

在这个 Bot 资料面板的「权限」标签里查看和撤销。

例行任务

例行任务没有按时运行。
  • 电脑当时在睡眠:按 设置 › 例行任务 ›「电脑睡眠时错过的任务」处理(补跑、跳过或问你)。
  • Pi Bot 被完全退出:默认会停止例行任务。可以在 设置 › 例行任务 选「完全退出 Pi Bot 后:继续跑例行任务」,或在 设置 › 通用 › 启动 选「只在后台运行」,登录电脑时自动在后台启动。
  • 打开了「7 天没打开就暂停」,并且你超过 7 天没打开 Pi Bot。
  • 任务被停用:在例行任务页看卡片右上角的开关。
例行任务卡在「等你」。

它在等一项审批。到「待办」里处理,或给这个任务加「本任务预授权」。

执行端与手机

执行端显示离线。
  • 确认那台机器开着、执行端在运行:pibot runner status。Linux 上可以 systemctl --user status pibot-runner。
  • 两端要用同一个中继,电脑上的「允许已配对设备连接」要打开。
  • 网络恢复后执行端会自动重连。离线期间选不了它的文件夹,正在等它的步骤会失败,等它上线后重试或改用本机文件夹。
配对码无效。

配对码 10 分钟后过期,且只能用一次。在执行端上重新运行 pibot runner pair,复制完整的配对码。

手机一直显示「电脑离线」。

电脑需要开着且 Pi Bot 在运行(关掉窗口没关系,完全退出不行),设置 › 设备 里「允许已配对设备连接」要打开。手机开了 VPN 时,请在 VPN 里让 Pi Bot 绕过,否则只能经中继连接。安卓系统省电可能断开后台连接:在应用信息里把「电池」设为「不受限制」,或打开「保持连接」。

手机离线时 Bot 不回复。

这个 Bot 没开离线回复,或它用的模型不能在手机上用(订阅登录、云厂商凭据、自定义请求头只留在电脑上)。在电脑的 设置 › 设备 › 这台手机 ›「电脑离线时」里查看。

其他

怎么换语言或深色模式?

左下角头像菜单里直接切换,或 设置 › 通用 › 语言和外观。语言只改菜单和按钮,Bot 用什么语言回答,看你怎么跟它说话。

关掉窗口后 Pi Bot 还在运行吗?

在。它在托盘 / 菜单栏里继续运行,例行任务照常跑。要完全退出,用托盘菜单里的「完全退出」。

提示系统密钥库不可用。

Pi Bot 用系统密钥库加密保存 Key。Linux 上需要一个运行中的密钥环服务(如 GNOME Keyring 或 KWallet);确认已登录桌面会话后重启 Pi Bot。