故障排除

当仪表板看起来与你的机器不同步、某个会话消失，或某个托管 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 提供方无法启动

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

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 控制界面问题，而非通用的仪表板故障。

通知没有到达

在仪表板中打开 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