OpenBot 故障排查¶

OpenBot 提示需要设置代理 CLI¶

打开终端并验证 CLI：

codex --version

如果命令缺失，请使用官方安装程序安装 Codex：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

然后运行 codex login，使用 ChatGPT 登录，完全退出 OpenBot，然后重新打开它。

你也可以改用 Claude。验证并安装 Claude CLI：

claude --version
curl -fsSL https://claude.ai/install.sh | bash
claude auth login

如果 Codex 安装在非标准位置，请将 OPENBOT_CODEX_PATH 设置为 Codex 可执行文件的绝对路径，然后启动 OpenBot。

对于非标准的 Claude 位置，请将 OPENBOT_CLAUDE_PATH 设置为 Claude 可执行文件的绝对路径。

Linux AppImage 立即退出¶

在 Ubuntu 23.10 或更高版本、以及 Debian 13 上，非特权用户命名空间受到 AppArmor 的限制。Electron 沙箱构建在用户命名空间之上，因此 OpenBot 在启动期间会退出，并向终端写入一条关于 SUID 沙箱或用户命名空间的消息。

安装 OpenBot 附带的 AppArmor 配置文件，然后重新加载 AppArmor：

sudo install -m 0644 build/linux/openbot.apparmor /etc/apparmor.d/openbot
sudo systemctl reload apparmor

同一文件位于 AppImage 内的 resources/linux/openbot.apparmor。配置文件会附加到常见位置以保留 AppImage；如果你的 AppImage 在其他位置，请先编辑配置文件中的路径再安装它。

不要使用 --no-sandbox 启动 OpenBot。这不是受支持的解决方法。沙箱是 Web 渲染器与计算机其余部分之间的边界，而 OpenBot 在其另一侧赋予其代理完全本地访问权限。

Linux AppImage 提示未找到 fusermount 二进制文件¶

AppImage 使用 FUSE 挂载自身。它不需要 libfuse2，但需要 fusermount3 程序。安装 fuse3 软件包（在 Arch Linux 和 Omarchy 上运行 sudo pacman -S fuse3，在 Ubuntu 和 Debian 上运行 sudo apt install fuse3），然后重新启动 AppImage。如果没有 FUSE（例如在容器中），请使用 --appimage-extract-and-run 启动它。

Linux 上缺少远程桌面¶

Linux 上的远程桌面需要 x64 AppImage 和 X11 会话。Sunshine 捕获 X11 屏幕，并通过 XTest 扩展发送鼠标和键盘输入。在 Wayland 下，或没有 DISPLAY 时，远程桌面会报告需要 X11 会话。请使用 Xorg 会话登录，或在服务器上通过 xvfb-run 启动 OpenBot。arm64 AppImage 不包含该运行时。

在较旧的 Linux 上语音提示失败¶

x64 AppImage 的语音运行时需要 glibc 2.32 或更高版本，例如 Ubuntu 22.04 或 Debian 12。在 Ubuntu 20.04 或 Debian 11 上，听写模型会下载，但运行时无法加载，语音提示会显示错误。请使用更新的发行版。arm64 AppImage 需要 glibc 2.17 或更高版本。

OpenBot 在 Linux 上因 GPU 而运行缓慢或停止¶

在 Linux 上，OpenBot 会使用 GPU，直到 GPU 在您的计算机上发生故障。如果 GPU 进程崩溃，或启动在前 30 秒内停止，OpenBot 会在 ~/.config/OpenBot 中写入 gpu-crash.json 或 gpu-start.json。只要存在其中一个文件，OpenBot 就会在 CPU 上渲染。此时，带有模糊背景的对话框和面板会变得更慢。包含新 Chromium 版本的更新会再次尝试使用 GPU。GPU 上下文丢失后（例如挂起后）的 GPU 进程重启不算数。服务器（OPENBOT_SERVER=1 或托管服务器）始终在 CPU 上渲染。

• 要再次尝试使用 GPU，例如在驱动更新后，请删除该文件。日志会写明其名称。
• 要始终使用 GPU，请使用 OPENBOT_DISABLE_GPU=0 启动 OpenBot。
• 如果 OpenBot 每次启动都会停止，请使用 OPENBOT_DISABLE_GPU=1 启动它，以始终在 CPU 上渲染。

Computer Use 不可用¶

Computer Use 需要 cua-driver 二进制文件。已安装的发行版自带该文件，因此面板报告缺少驱动意味着您使用的是开发构建，或者文件已被删除。在 macOS 上，它还需要“屏幕录制”和“辅助功能”权限；Windows 和 Linux 不需要请求任何权限，因此能够响应的驱动即可就绪。OpenBot 自行启动驱动；它不会绕过 macOS 的提示。

如果已安装的发行版报告驱动缺失，请重新安装完整的 OpenBot 软件包，然后重新启动 OpenBot。请保留您的 OpenBot 数据文件夹。单独安装驱动无法修复已安装的发行版，因为应用程序只使用其捆绑的驱动。

在开发检出中，运行 bun run prepare:cua-driver，然后在面板中点击“重试”。此命令会写入发行版随附的同一个固定构建。bun run cua-driver:doctor 会报告 OpenBot 将使用哪个二进制文件，而 OPENBOT_CUA_DRIVER_PATH 可选择另一个。已安装的应用程序会忽略该变量：它只运行随发行版提供的驱动。

在 Linux 上，驱动通过 AT-SPI 读取桌面，因此它需要所驱动桌面的会话总线。从容器、通过 runuser、或以 root 身份针对其他用户会话启动的守护进程会发现空的辅助功能树，并且 get_window_state 报告 degraded。X11 是驱动完全支持的 Linux 会话。在 Wayland 上，OpenBot 以 CUA_DRIVER_RS_ENABLE_WAYLAND=1 启动驱动；如果您的合成器通过 XWayland 工作得更好，请自行将该变量设置为 0。GNOME 下的窗口矩形还需要驱动自己的 winrects@cua shell 扩展，其安装程序会刷新该扩展，但不会为您启用它。

如果面板报告需要权限，请打开“系统设置 → 隐私与安全性”，并同时授予“屏幕与系统音频录制”和“辅助功能”，然后点击“重新检查”。开发构建会以“Electron”而非 OpenBot 的身份请求这些授权，因为开发二进制文件是负责的进程。出于同样的原因，开发授权不会延续到已安装的发行版，每个构建都必须授权一次。

Computer Use 响应缓慢¶

Computer Use 步骤包含两个部分：驱动执行操作，然后模型读取结果并选择下一步操作。驱动工作时，聊天中的活动行会显示“正在此计算机上使用应用…”。模型工作时，它会显示“正在决定应用中的下一步…”。当代理写入自己的进度说明时，该行会改为显示该说明。当该行在 5 秒内保持不变时，自其发生变化以来经过的时间会显示在文本旁边。

驱动程序调用通常只需几秒或更短。要查看每次调用的耗时，请从终端启动 OpenBot。每次耗时 5 秒或更长的驱动程序调用会在其输出中显示为 Computer Use driver answered，并附有工具名称和毫秒数。在代理关闭连接前未收到响应的调用显示为 Computer Use driver did not answer。设置 OPENBOT_LOG_LEVEL=debug 可显示每次调用。日志不包含代理输入的内容。

缓慢步骤中的大部分时间都花在模型上。其耗时取决于模型以及代理设置中的推理力度：高推理力度可能在每个操作前花费数十秒。对于机械性的 GUI 任务，请选择较低的推理力度或更快的模型。在请求中说明应用程序和操作，例如“在 Safari 中打开 https://example.com”，这样代理就不会先去寻找目标。

随着对话变长，每一步也会变慢。模型在每个操作前会读取完整对话，每次读取的窗口内容都会保留在其中。当对话填满模型的上下文时，提供商会对其进行压缩：它会写入一份摘要，这可能需要几分钟，而聊天界面在此期间不会显示任何操作。针对新的 GUI 任务开启新对话则没有这种开销，而且代理会保留其工作区。使用 OpenCode 时，OpenBot 会将每次驱动程序结果的 JSON 副本添加到结果文本中，因为 OpenCode 只向模型显示文本。该副本不包含元素列表，因为文本中的树已经按索引命名了每个元素。

更新后聊天记录丢失¶

不要执行下面的重置步骤。你的消息存储在一个 SQLite 文件中，升级前不会复制该文件，如果移动该文件夹，唯一的一份副本将无法访问。

先退出 OpenBot 并重新启动。当代理与其聊天记录彼此失去关联时，OpenBot 会在启动时将该聊天记录归还给所属的代理，因此大多数情况下重启即可自行恢复。

如果聊天记录仍然缺失，请退出 OpenBot 并直接读取该文件。以下命令会报告当前没有任何代理认领的聊天记录，以及每个聊天记录中等待的消息数量：

sqlite3 "$HOME/Library/Application Support/OpenBot/openbot.db" \
  "SELECT t.thread_id, t.agent_id, (SELECT count(*) FROM projection_thread_messages m
     WHERE m.thread_id = t.thread_id) AS messages
   FROM projection_threads t
   LEFT JOIN projection_agents a ON a.agent_id = t.agent_id
   WHERE a.agent_id IS NULL;"

只要有任何一行，就说明消息仍在磁盘上并且可以恢复。请将输出连同下面的详细信息一起报告，在此之前保持该文件夹的位置不变。

OpenBot 无法启动并提示某个已存储的代理配置文件¶

消息内容为 Stored agent profile <id> has an unreadable "<field>" value。你的数据完好无损：OpenBot 在写入任何内容之前就停止了，这正是配置文件保持原样的原因。

不要执行下面的重置步骤，也不要移动该文件夹。请先安装当前版本：OpenBot 现在会修复无法读取的已存储配置文件字段，并保留代理、其聊天记录和工作区，而该修复之前的版本则会拒绝在同一个配置文件上启动。

如果当前版本仍然停止运行，请退出 OpenBot 并读取它提到的配置文件。在 macOS 上：

sqlite3 "$HOME/Library/Application Support/OpenBot/openbot.db" \
  "SELECT agent_json FROM projection_agents WHERE agent_id = '<id>';"

在 Windows 上，同一文件位于 %APPDATA%\OpenBot\openbot.db。

请报告消息中提到的字段，以及下面的详细信息。输出内容包含你自己的文件路径，发布前请先检查。

计算机休眠时例程不运行¶

例程仅在计算机处于唤醒状态且 OpenBot 打开时运行。

• 休眠后，当网络恢复时，每个逾期的例程会运行一次。OpenBot 不会补跑错过的每一次。
• 如果 OpenBot 已关闭，例程设置“如果在预定时间 OpenBot 已关闭”会决定：跳过运行，还是在 OpenBot 打开时运行一次。

在 macOS 和 Windows 上，打开设置 → 常规 → 保持此计算机唤醒。当计算机接通电源时，空闲状态下它就不会休眠。显示器仍然可以关闭。合上笔记本电脑盖或手动选择休眠仍会使计算机休眠，除非 macOS 使用外接显示器（合盖显示模式）。使用电池供电时，计算机照常休眠，除非你也打开使用电池时也保持唤醒。

pmset -g assertions 可以显示名为 WebRTC has active PeerConnections 的 OpenBot 条目。该条目仅在另一台设备连接到这台计算机时存在，因此该设备断开连接后计算机即可休眠。启用该设置后，条目名称变为 Electron。

要查看 Mac 何时休眠，请运行 pmset -g log | grep -E " Sleep | Wake "。当 OpenBot 开始保持唤醒时，logs/main/main.log（参见报告问题）中会有一行 Keeping this computer awake.。对于需要在你没有任何计算机开启时运行的例程，请使用托管服务器或自托管服务器。

公司防火墙或代理阻止了 OpenBot¶

当网络过滤器（如 Fortinet）代替 OpenBot 服务进行响应时，登录会显示“此网络上的防火墙或代理阻止了 OpenBot 访问 <host>”。这种情况发生在过滤器显示阻止页面，或使用计算机不信任的根证书检查 TLS 时。

OpenBot 像浏览器一样信任操作系统证书存储中的根证书。如果公司在计算机上安装了其检查证书，OpenBot 会接受它。OpenBot 启动的代理 CLI（如 Codex 和 Claude）会按照自己的规则检查证书。不要关闭证书检查来绕过阻止。

请让网络管理员允许这些主机通过 HTTPS（TCP 443）和 WebSocket 访问：

团队和远程服务器还会将 WebRTC 流量发送到其他设备，或发送到 Signal 指定的 TURN 中继，并使用它指定的 UDP 和 TCP 端口。阻止 WebRTC 的过滤器会使这些连接变慢或中断。对话保留在计算机上；隐私政策列出了每个主机接收的内容。

如果过滤器将 openbot.run 归入被阻止的类别，管理员可以请求供应商审核它。对于 Fortinet，请使用 FortiGuard Web 过滤查询。

重置 OpenBot¶

在移动数据之前退出 OpenBot。要在保留智能体工作区的同时重置应用程序状态和共享浏览器配置文件，请将此文件夹移到安全位置：

~/Library/Application Support/OpenBot

要同时重置智能体工作区、托管传输和下载内容，也请移动此文件夹：

~/OpenBot

OpenBot 会在下次启动时创建全新的文件夹。请先查看并备份其中的内容。除非你确实想手动管理 CLI 登录和历史记录，否则不要删除 ~/.codex 或 ~/.claude。

卸载¶

退出 OpenBot。在 macOS 上，从“应用程序”中删除 OpenBot.app；在 Windows 上，使用安装程序的卸载程序；在 Linux 上，删除 AppImage、~/.local/share/applications/openbot.desktop、~/.local/share/icons/openbot.png，如果你安装了配置文件，还要删除 /etc/apparmor.d/openbot。如果你还想删除 OpenBot 本地数据，请按照上面的重置步骤操作。Agent CLI 及其数据是独立的，不会随 OpenBot 一同删除。

报告问题¶

对于可重现的 bug，请使用 bug 报告表单。表单要求提供平台、OpenBot 版本（桌面端：设置 → 更新；手机端：设置 → 关于）、操作系统和硬件、提供商及其 CLI 版本、操作步骤，以及预期结果和实际结果。当某一提供商行显示错误时，请在其菜单中选择 Copy diagnostics，并将结果粘贴到表单中。在手机上，设置 → 支持 → Save log file 可生成可供附加的日志。切勿发布令牌、~/.codex、~/.claude、对话内容、私人文件、Electron 用户数据或未经审核的完整诊断信息。

当桌面应用自行关闭时，请查看其用户数据中的 logs 文件夹（Windows 上为 %APPDATA%\OpenBot\logs，macOS 上为 ~/Library/Application Support/OpenBot/logs，Linux 上为 ~/.config/OpenBot/logs）：

• main/main.log 在 OpenBot 自行退出或被关闭时包含一行 Quitting: <reason>.。
• trace.ndjson 包含一行具有相同原因的 exit，并为每个停止的渲染进程或辅助进程包含一行 crash。

logs 旁边的 Crashpad 文件夹中存在 dump 文件意味着某个进程发生了崩溃。请告知我们存在 dump 文件，但不要公开附加它：其中可能包含机密信息。当两个文件都没有给出原因且没有 dump 文件时，说明是 OpenBot 之外的某个因素停止了它。