Herdr GPUI 连接排障：按组件逐层检查

桌面连接失败可能来自不同组件。请分别检查后台程序、客户端、编程 Agent 与远程访问。本清单提供逐层顺序，避免重新安装无关组件。

返回 Herdr GPUI 概览与步骤生成器

应用找不到 Herdr

在普通终端检查可执行文件：

command -v herdr

找不到时，先参考后台程序安装指南。能找到时，记录文件位置与安装方式。客户端文档说明了 PATH 与常见安装位置的发现机制，以及安装后的 Terminal > Reconnect 操作。

应用可以启动已安装的本地服务器，但不会安装后台程序。显式 socket 和开发目标有不同的连接行为，修改自定义目标前先读客户端文档。

终端能连接，但 Agent 无法启动

在普通终端中检查选定 Agent 的命令，确认其自身安装、认证和项目访问。

登录或模型权限错误属于 Agent 配置。安装桌面界面不会提供账号与凭据。普通终端能启动时，再比较失败窗格的目录与环境。

若只是状态显示异常，检查终端输出和集成配置。Agent 文档说明检测与集成方式。阻塞可能是正常审批请求，不一定是连接故障。

远程主机无法连接

先验证实际配置主机的普通 SSH 访问，再检查远端是否具备 Herdr、项目和 Agent 环境。

区分主机不可达、认证失败、主机密钥未信任，以及后台程序不可用。本地图形主题无法修复这些条件。

同时参考 Herdr 远程主机指南与客户端要求。图形客户端和终端界面的平台能力并不完全一致；客户端文档列出了保存 SSH 主机等功能的平台限制。

不要仅因界面断开就重试编码任务。恢复连接后，先检查已有终端活动，再判断是否需要启动新任务。

工作区恢复了，但程序不见了

正常分离客户端可以保留后台进程，服务器或机器重启则不能让原进程存活。

恢复布局和续接受支持的 Agent 对话，不等于恢复全部 shell、测试进程或服务。先确认运行时实际经历了什么，再查阅会话状态与恢复文档。重新出现的窗格，不证明原程序仍然运行。

重启任务前保留仓库修改，并检查已保存进展和当前输出，避免重复工作。

字体或主题与预期不符

区分客户端偏好与 Herdr 共享设置。文档说明 config-gpui.local.toml 保存持久覆盖，config-gpui.toml 保存受管理默认值；应用可能替换后者，因此直接编辑默认文件可能不生效。

修改前查阅当前配置文档。记录具体选项，以及它影响本地界面还是远端环境。每次只改与故障有关的设置，便于判断解决原因。

准备有效的问题报告

提供操作系统、安装方式、客户端版本、后台程序版本、本地或远程目标、失败操作与准确错误，并说明可执行文件检查、普通 SSH 和 Agent 启动是否成功。

从日志中移除凭据、令牌和私有项目内容。本站示意图不能作为软件会话实际运行的证据。

安装检查可返回macOS 配置指南，连接稳定后再参考独立 Agent 工作树规划。