故障排查

检测不到 Agent

先在终端执行相应命令的 --version。安装桌面程序不等于安装了 CLI/ACP。Windows 可用 where.exe opencode 查看路径，Linux 使用 command -v opencode。

手动安装后重新检测；使用 nvm/nvmd 时确认当前 Node 版本，每个版本的全局包可能不同。终端能运行但工作台不能时，指定实际可执行文件路径并运行诊断。

表示命令包装器格式不受当前版本支持，程序可能尚未执行。0.1.2 支持常见 npm/nvm/nvmd 格式；其他自定义包装器请指定真正的 exe 或 Node 入口，避免任意批处理逻辑。

当前固定协议版本为 0.162.0-alpha.2。核对工作台实际检测路径与 codex --version，不要只看另一个终端中的版本。多个 Codex 安装可能指向不同文件。

表示 Agent 找不到该原生会话的历史。可能涉及已删除历史或不同 Agent 数据目录。先保留工作台历史，核对登录和运行环境；无法恢复时新建会话，复制必要上下文继续。

检查可信用户、接收者和会话绑定；再检查目标 Agent 可用性、待审批状态、平台事件订阅与机器人权限。连接状态不代表消息与回调都通过。

检查网络和更新通道。Beta 清单不存在会失败，可切换稳定通道重试。下载失败稍后重试；安装按钮受运行任务或审批阻止时，先完成任务与审批。

不同桌面环境可能不支持托盘或 Wayland 全局键。以实际能力提示为准，保留可见窗口和应用退出入口。

记录软件版本、系统、Agent 名称、复现步骤和完整错误，附脱敏诊断报告。请勿发送密钥、token 或带敏感项目内容的截图。联系维护者：zovv8569@gmail.com。