常见问题
先确认配置，再核对实际请求，最后处理记录与恢复。
保存成功，但客户端没有使用新服务
保存只更新配置，不代表客户端已经发起请求。 请在模型页明确选择服务和模型。 标记“需 Trace”的模型，应先开启 Trace。
如果客户端仍使用旧连接，请重新打开客户端再试。 在仪表盘核对新请求的实际上游。
模型列表为空或刷新失败
检查当前连接的地址、密钥和目录访问权限。 Coding Plan 套餐可能使用专属接口地址。 不要把网页聊天地址当作 API 地址。
目录失败会保留已有成功缓存和选择。 模型菜单只显示实际目录。 已有的自定义或下线型号会保留，不会自动换型。
请求失败
- 核对所选服务、模型和账号。
- 在请求详情查看上游状态与错误原因。
- 在服务商后台核对权限、余额和可用模型。
- 修正问题后，再明确发起新请求。
普通限流、身份或网络错误不会自动跨服务重放。 已有部分输出或工具执行时，先检查任务结果。 不要把失败后的重复任务视为安全续接。
Trace 开着，但没有记录
确认客户端已接入本机 Gateway。 开启 Trace 后，新建一段测试对话。 旧对话可能继续使用原先绑定的连接。
下载过客户端不等于已经完成接入。 查看模型页和 Trace 页的实际状态提示。
提示配置被外部修改
其他工具或客户端可能改动了同一配置文件。 XwX Deck 会保留外部变化，不会直接覆盖。 检查变化来源，再按提示选择重新应用或恢复连接。
Trace 记录缺失或索引异常
打开“设置”中的“诊断与修复”，检查 Trace 记录。 只有检测到索引问题时，才会提供修复入口。 停止 Gateway 后，由用户手动发起修复。
修复会备份原索引，不改写原始 JSONL。 如果详细记录已被清理，索引修复不会还原正文。 保留的用量统计仍可继续查看。
无法安全退出
先检查是否仍在生成回复，或等待工具返回。 按提示继续等待，或明确停止活动请求。
如果客户端配置仍依赖本地端口，应用会保留 Gateway。 处理配置恢复失败后，再退出应用。 不要在客户端仍依赖本地端口时直接结束进程。
更新或安装遇到问题
安装步骤见 下载与安装。 macOS 下载完成后，点击“打开安装包”。 等待旧应用退出，再将新版拖入“应用程序”替换。 Windows 更新后自动启动失败时，按提示手动打开程序。
检查更新失败不代表当前已是最新版本。 请查看发布页，确认是否提供对应平台的新版本。
提交反馈
在 GitHub Issues 记录问题。 附上应用版本、系统版本、复现步骤和实际结果。 日志或截图应先脱敏，避免提交密钥和完整业务正文。