故障排除

当仪表板看起来与你的机器不同步、某个会话消失，或某个托管 CLI 运行时需要恢复时，请使用本页。

仪表板中什么都没显示

如果仪表板显示没有机器或会话，请先检查本地守护进程：

adhdev daemon:status

查看：

• 一个正在运行的守护进程进程
• 可达的本地 IPC
• 如果你使用 CLI 代理，则查看 session-host 状态

如果守护进程未运行，请再次启动它，或者如果你通常以后台服务方式运行 ADHDev，则重新安装该后台服务。

缺少某个 IDE 或代理

在重新启动任何东西之前，请检查那些现在会隐藏不太紧急工作的仪表板界面：

• 隐藏标签页
• 活动收件箱
• 历史

如果机器已连接，但缺少某个特定的 IDE 会话，请通过 ADHDev 重新启动该 IDE，使它以预期的控制界面启动：

adhdev launch cursor

请为你的 IDE 使用相匹配的目标。

聊天看起来为空或卡在加载中

如果会话存在，但聊天为空白或仍在加载：

1. 等待几秒钟让会话流稳定下来。
2. 从标签条、收件箱或历史中重新打开会话。
3. 检查原始的 IDE 或 CLI 工具是否仍在运行。
4. 如果它是一个 CLI 运行时，请检查 session host，而不是立即启动一个重复会话。

对于 CLI 密集的设置，缺失的聊天往往意味着运行时幸存了下来，但仪表板需要重新连接到它。

会话看起来永远卡在“生成中”

如果一个 CLI 会话显示“生成中”的时间远超任务应花的时间，先检查该代理上的 无进展提醒设置（仪表板齿轮按钮）—— 一旦某个轮次运行超过阈值它就会发出通知，这往往是出问题的第一个真实信号，而不仅仅是一个较长的轮次。如果终端本身看起来冻结或乱码（最常见于 Antigravity CLI 在某些工具输出之后），重新打开该会话 —— ADHDev 会推动一次重绘并重新检查真实状态。如果之后仍然卡住，请使用上面的 session-host 恢复路径，而不是强行关闭并重新启动一个重复会话。

CLI 提供方无法启动

如果启动器提示没有可用的 CLI 提供方，或某个内置提供方在启动中缺失：

1. 打开机器的 Providers 标签页。
2. 在该机器上启用该提供方。
3. 运行 Detect 并阅读提供方卡片上的检测/验证详情。
4. 如果上游二进制文件安装在默认 PATH 之外，请设置自定义可执行文件路径/参数。
5. 如果你更改了提供方源模式或 providerDir，请在尝试新的启动之前点击 Apply + Reload。

内置提供方清单有意与机器可启动性分开。只有在本地激活和检测成功之后，某个提供方才变得可启动。

重启后 CLI 会话卡住

托管 CLI 运行时现在有一条专用的恢复路径。

首先检查 session-host 状态：

adhdev daemon:session-host

常见的恢复操作：

adhdev daemon:session-host --session <sessionId> --resume
adhdev daemon:session-host --session <sessionId> --restart
adhdev daemon:session-host --prune-duplicates

你可以从仪表板中机器的 Hosted Runtimes 标签页执行相同操作。

在以下情况使用它：

• 某个 CLI 会话在守护进程重启后幸存
• 某个运行时卡在 interrupted 状态
• 为同一会话创建了重复的托管运行时
• 某个运行时仍然存在，但仪表板连接到了错误的副本

远程视图不可用

如果远程视图为空白或显示 CDP 警告：

1. 通过 adhdev launch <ide> 重新启动 IDE。
2. 确认该 IDE 是 ADHDev 能够良好控制的基于 Electron 的流程之一。
3. 检查你的网络或浏览器是否干扰了实时连接。

如果会话的其余部分工作正常但远程视图不行，请先将其视为 IDE 控制界面问题，而非通用的仪表板故障。

某个 CLI 会话看起来空闲但从不响应

如果一个 CLI 会话什么都没做却立即"响应"，或者看起来空闲但实际上无法使用，请检查底层工具的登录是否已过期 —— 常见原因是该 CLI 自己报告的登录/会话/凭据已过期（"Login expired"、"session has expired" 等）。ADHDev 会按会话检测这种情况，并将该会话标记为出错，而不是让它看起来像一个健康的空闲工作者。重新对该工具进行认证（使用它自己的登录命令），然后重新启动或重新连接该会话。

Repo Mesh 在分派时跳过某个提供方

如果一个 Repo Mesh 任务始终没有被你预期会认领它的节点认领，请检查该节点的提供方当前是否报告了配额/用量限制耗尽（adhdev quota <provider>）。mesh 队列在得到某个提供方已耗尽的最新读数时，会刻意不向其分派新工作，而是路由给另一个空闲节点。一旦配额重置（或你运行 adhdev quota refresh <provider>），该节点就会重新变得可用。

Windows 更新期间控制台窗口闪现（1.0.60 部分修复）

在 Windows 上，当 adhdev update 运行期间以及守护进程在新版本上重启之后，控制台窗口可能会短暂闪现。1.0.60 已从更新流水线本身（npm install、原子安装替换以及健康检查轮询）中移除了这些闪现，也修复了升级后的守护进程启动后针对每个已安装 CLI 提供方各闪现一次的问题（它会探测每个 CLI 的 --version）。目前仍有一处已知闪现正在处理中：停止某个会话时出现的 node.exe 窗口，它来自一个第三方库调用，该调用本身没有隐藏窗口的选项。这只是视觉上的问题 —— 会话停止仍会正常完成。如果你在其他时刻看到闪现，请连同窗口标题一起报告。

通知没有到达

在仪表板中打开 Notifications 并验证：

• 全局通知已启用
• 浏览器通知已启用
• 如果你使用托管云路径，推送通知已启用
• 提供方级别的提醒设置没有抑制你期望的事件

推送通知仅限云端，并且在移动端把 ADHDev 安装为 PWA 时效果最佳。

移动端仪表板感觉卡住

移动浏览器在挂起后台标签页方面更为激进。

请尝试：

1. 下拉刷新
2. 从收件箱重新打开活动会话
3. 如果连接没有恢复，则完全重新打开该标签页

如果你只需要检查批准，收件箱通常比等待之前的聊天视图自我恢复更可靠。

仍然出问题

如果本地状态看起来不一致，请先收集当前状态：

adhdev doctor
adhdev daemon:status
adhdev daemon:session-host --json

adhdev doctor 现在还会检查 PATH 中的 adhdev / adhmux 二进制文件是否陈旧、损坏或缺少更新的运行时界面。如果 runtime 命令看起来与文档不一致，请在假定 session-host/运行时层有问题之前先检查 doctor 输出。

然后检查：

• ~/.adhdev/logs/ 中的守护进程日志
• 仪表板中机器的 Logs 标签页
• 机器的 Hosted Runtimes 标签页中被中断的运行时

最后手段

如果安装本身已损坏，干净地重新安装仍然是后备方案：

adhdev uninstall -f
npm uninstall -g adhdev
npm install -g adhdev
adhdev setup
adhdev service install

WARNING

这会移除本地 ADHDev 数据，包括认证状态、日志和缓存的配置。

获取帮助

• 兼容性与注意事项
• 仪表板
• CLI 代理
• Self-hosted
• GitHub Issues: github.com/vilmire/adhdev/issues