CodeNomad 故障排查
恢复时先检查失败操作由谁负责：浏览器、CodeNomad 后端、OpenCode 服务或提供商。回复丢失不证明修改失败；重复前先重读当前状态。
桌面启动问题
macOS 隔离
CodeNomad 的 macOS 发行版未经 Apple 公证，因此即使是从官方仓库下载并已验证的副本，macOS 也可能阻止其首次启动：可能显示 "CodeNomad" Not Opened（Apple 无法验证其不含恶意软件），或提示应用已损坏。
- 检查下载来源和已安装应用路径。
- 如果应用安装在以下路径，请移除其隔离属性：
xattr -dr com.apple.quarantine /Applications/CodeNomad.app
- 再次启动。对于 Not Opened 消息，也可以在启动被阻止后，在 System Settings → Privacy & Security 中为 CodeNomad 选择 Open Anyway，并用管理员密码确认。
这会更改该应用的 macOS 隔离属性。不会修复损坏下载，也不会使未知二进制变可信。
Linux 图形与 FUSE
Wayland/NVIDIA 上立即退出的 Tauri AppImage 可能受到 WebKitGTK DMA-BUF/GBM 渲染器影响。使用针对性的环境覆盖运行下载的 AppImage：
WEBKIT_DISABLE_DMABUF_RENDERER=1 ./CodeNomad-Tauri-linux-x64-<version>.AppImage
Electron 使用 Chromium，可作为同一主机上的替代方案。如果 AppImage 因 FUSE 不可用而无法挂载，请使用 --appimage-extract-and-run；参阅 Linux 安装。这些修复无需禁用 Electron 沙箱。
Git 与工作区可用性
- 检查后端账户
PATH中的 Git，而非仅检查智能体 Shell 内的 Git。 - 缺少时为该主机/账户安装 Git，然后重启 CodeNomad 后端以继承更新环境。
- 重新打开/刷新工作区并检查仓库状态。
没有 Git 时仍可使用仅目录对话；工作树和 Git 控件不可用。Windows 上只在 WSL 内安装 Git 不足以满足 Windows 后端。没有仓库的已知文件夹可显示初始化 Git；缺少 Git 可执行文件是不同情况，必须先修复。参阅要求和文件。
无法验证所属工作树或对话位置时，请显式打开其物理文件夹，而非尝试任意路径或编辑原生存储。移动/移除结果不确定后，请刷新查看实际存在的位置。强制移除工作树可能销毁未提交文件；不要用它修复连接。
OpenCode 运行时与 WSL
- 打开偏好设置 → OpenCode，检查 OpenCode 版本卡片（已安装版本和运行服务状态），然后检查 OpenCode 可执行文件下所选的可执行文件。
- 缺少必需运行时时，使用受支持安装/更新操作。当前最低：2.1.2；推荐/已验证：2.1.4。
- 已安装 CLI 与运行服务不同时，显式决定是否重启共享服务。
故障排查下提供重启 OpenCode 服务，需要确认。会中断所有已连接客户端的活动工作，但保留会话历史。重新加载配置是独立操作：保留进程，但重建已加载 Location 并取消待处理问题/权限。两者都不是无害刷新。
对于 WSL 可执行文件，确认目标发行版和 Windows localhost 转发。服务生命周期在 Linux 内运行；CodeNomad 仍须从 Windows 访问其回环端点。切勿从 Windows 编辑服务注册/数据库或向猜测的 Linux 进程 ID 发送信号。
自定义/更新版本可能未经验证，但并非不兼容。更改版本前请阅读实际契约错误。会话环境同步失败时，请修复执行主机环境/连接：未完成同步，CodeNomad 不会发送提示词。参阅 OpenCode。
登录、TLS 与直接连接
| 症状 | 安全检查与恢复 |
|---|---|
| 重新登录 CodeNomad | 保持页面打开，输入服务器用户名/密码并选择登录。恢复会就地重连以保留草稿；不会重放失败操作。 |
| 服务器不可达 | 确认后端运行，使用打印地址/实际端口。仅不可达检查不证明登录过期。 |
| 提供商拒绝认证 | 通过提供商登录所属方修复；不要为修复提供商 OAuth 更改 CodeNomad 服务器密码。 |
| 证书名称/信任错误 | 检查实际主机名/IP 与证书 SAN 是否匹配，安装预期 CA 信任或有效服务器证书。不要禁用 TLS 验证。 |
| 直接连接被拒绝 | 检查实际 HTTP/HTTPS 绑定、防火墙和路由。桌面或双监听器模式中的 HTTP 保持回环；独立 HTTP-only 绑定行为不同。 |
认证恢复后，手动重试回复不确定的修改操作之前，请检查状态。运行时密码必须每次后端启动都提供；通过设置保存的密码会持久保留。参阅安全、TLS/绑定规则和服务器参考。
远程控制配对
- 在主机打开设置 → 远程访问，检查远程控制正在运行。
- 创建新配对链接，在过期前于目标设备打开。
- 如果客户端显示重新配对此设备，从主机配对，然后在客户端选择检查连接。
配对链接一次性且短期有效；直接访问密码不能替代。已撤销或因不活动过期的设备凭据需要重新配对。关闭最后一个桌面窗口会停止其后端，因此也停止远程控制；启用的服务会在下次应用启动时恢复。主机专用不可用界面和撤销参阅远程控制。
提供商、插件和扩展状态
| 问题 | 恢复 |
|---|---|
| 提供商账户/配额错误 | 检查所选原生账户和用量。配额显示不是 Token/成本总量。账户更改不确定时请刷新；选择可能影响该服务其他客户端。 |
| 外部所有的 OAuth 过期 | 通过 OpenCode、Claude Code 或相关凭据所属方重新登录。CodeNomad 不交换其刷新令牌。 |
| 自动轮换不切换 | 检查是否主动启用、是否符合条件，以及当前账户是否确实耗尽。这是接纳前策略，不是运行中故障转移或提示词重放。 |
| 插件状态似乎过时 | 使用刷新插件控件，检查插件工具提示的范围/目标；运行时激活可能等待原生刷新。不要反复切换未确认写入。 |
| 任务控制台不可用 | 按其指出的原因处理。如果 OpenCode 尚未加载任务插件，请刷新；问题仍然存在时使用重新加载 OpenCode 配置。如果插件加载失败，请在插件列表中查看其错误。如果服务器无法打开其本地任务连接，请检查服务器日志，因为重新加载 OpenCode 无济于事。任务也可在独立服务器上运行。 |
| 已安装扩展缺失 | 检查面板自定义中唯一的激活复选框。安装/替换后保持禁用，直到显式激活并批准所需同意。 |
| 扩展资源被拒绝 | 确认当前挂载会话的 API 2 资源读取同意。安装扩展不代表允许读取任意文件/历史。 |
历史、待处理请求和清理
完整历史搜索不局限于当前已加载的对话行。显示筛选隐藏内容而不删除；请通过历史区分搜索、压缩、技术清理和删除。
待处理请求恢复不完整时，CodeNomad 保留已知队列和回答草稿，而非将缺失覆盖视为空队列。连续两次恢复不完整后，会警告一次，并列出项目、原因、文件夹和受影响的会话；该警告属于项目和标签页通知类别（默认显示在屏幕上并记入历史，参阅设置 → 通知）。临时失败由存活检查重试。与压缩相关的延迟不表示请求已取消。请保留草稿、验证服务连接，依据请求当前状态再回答。
取消或部分清理时，开始另一轮删除前先阅读进度/回执。取消不撤销已派发批次。不要通过编辑原生数据库修复历史。任务结果不确定时，使用其检查状态/刷新恢复，而非创建另一运行或自动重放工作；任务说明重启和生命周期限制。
日志与安全诊断
- 打开实例信息查看状态；显示服务器日志提供可用输出。
- 在偏好设置 → OpenCode中，仅在需要更多细节时选择目标日志详细程度。独立 CodeNomad 日志请使用服务器 CLI 日志选项。
- 打开设置 → 信息 → 诊断，使用报告错误、复制到剪贴板或下载 .txt。
详细日志可能暴露路径、输出和应用数据。共享日志/截图前请脱敏凭据、配对链接、网络地址、私有路径和对话内容。完整诊断报告包含路径/地址；预填错误表单有意排除它们。参阅支持。