故障排查

从失败的操作和准确错误开始。修改设置前，记录 Wuu 版本、所选引擎、模型服务和工作区。不要先删除状态目录或反复启动同一任务：这会增加诊断难度，而且任务可能已经在后台运行。

桌面无法启动

完全退出应用后重新打开，确认安装包适合当前平台，且来自预期发布来源。如果 macOS 拦截应用，按安装指南处理，不要全局关闭 Gatekeeper。

初始化持续失败时，保留版本和可见错误。如果问题始于启用某个插件，按插件恢复操作，再尝试默认界面。

桌面窗口崩溃或变空白

渲染进程崩溃、内存不足退出、异常退出或启动失败后，Wuu 会重新加载该窗口。 自动重试最多三次，两次之间至少间隔五秒。连续失败后，原生对话框会提供 重新加载或关闭窗口。页面成功加载并保持一分钟后，重试次数会重置。 关闭窗口或退出应用会取消等待中的恢复。

已保存的会话仍然可用，恢复渲染进程不会重启 app-server。未发送的草稿及其他 未保存的窗口状态可能丢失。崩溃窗口拥有的终端会停止，避免留下无法操作的终端进程； 重新打开终端面板会创建新终端，其他窗口的终端不受影响。如果反复崩溃，报告时请提供 应用版本，以及已脱敏的 [renderer] process gone / recovery load failed 日志。

模型或引擎不可用

先确认会话使用 Wuu 引擎，还是外部 Codex、Claude Code 可执行程序。配置模型服务并不会安装或登录外部引擎。

Wuu provider 应检查服务接受的模型 ID、连接协议、API 前缀和认证。通过环境变量提供的 API key 必须存在于启动 Wuu 的进程中；在另一个终端中 export，不一定影响已经运行的桌面应用。能返回文本的网关，仍可能无法处理流式响应或工具调用。见模型服务。

wuu models 专门对 openai-codex 执行在线查询，不是所有 provider 的通用连接测试。

工作区不对或历史缺失

检查桌面所选工作区或 CLI 的 --workdir。Worktree 分叉有独立执行根目录，不绑定工作区的会话则使用 Wuu 临时工作区。默认会话列表按工作区筛选。

工作区目录移动后，应在原侧边栏条目上使用重新定位…。添加另一个相似名称的工作区不能修复原工作区身份。Worktree 丢失时，不要在弄清任务修改了哪些文件之前，直接把它指回主检出目录。

文件或命令被拒绝

从错误中确认被阻止的路径、权限模式或沙箱后端。Read only 会阻止修改；受限命令执行还需要正常工作的文件系统沙箱。后端不可用与路径越界是不同问题。

先登记正确工作区或修正命令，再考虑是否确实需要更大权限。Unconfined 是明确的权限扩大，不是通用修复开关。敏感文件保护和外部引擎控制另有规则，见权限。

没有新输出

命令可能在同步等待超时后转入受管理的后台进程。查看状态和增量输出，不要重复启动。输出很长时，即使界面只展示末尾，也可能提供完整日志引用。

排队提示会等待接收会话。模型服务失败、轮次暂停、工具运行中和轮次已完成是不同状态，应结合可见错误与已保存轨迹判断。界面与后端断开后，重新连接界面并不证明底层命令已经停止。

读取已保存诊断

Wuu 引擎的流请求失败后，可展开错误提示或重连卡片中的恢复详情。新的失败记录会保留自动重试次数、实际发出的请求数和停止原因，包括错误不可重试、重试或共享预算耗尽、工具重放不安全等；重新打开会话后仍可查看。这些次数只描述最后失败的流请求，不代表整个轮次或 token 计费量；旧的失败记录可能没有次数信息。未知错误不会仅因为包装文字包含“request failed”就自动重试。

响应数据过大表示单条事件超出 Wuu 本地接收上限，并非模型的 token 上下文窗口超限。SSE 数据载荷和 Responses WebSocket 消息每条最多支持 16 MiB，整个回答可以由多条事件组成。超过上限时不会自动重放或切换传输，因为两者都无法提高上限；请让模型分批输出，或更换模型连接。旧版本在 SSE 原有的 1 MiB 上限处可能报 read stream: bufio.Scanner: token too long，遇到此类错误应先更新 Wuu 再重试。

wuu version --long
wuu session list --json
wuu session show --json --last
wuu session trace --json --last

在相关工作区运行，或在位置参数前提供 --workdir。Trace 只读取已保存事件，不调用模型，也不重复工具副作用。执行 Run 清单使用 wuu runs，定时任务则查看自动化页面的运行历史。

提交有效报告

报告应包含版本和操作系统、桌面或 CLI 入口、所选引擎、最小复现步骤、预期与实际结果，以及相关脱敏错误。普通问题提交到 GitHub Issues。

不要上传整个 ~/.wuu 或 WUU_HOME 目录。配置、凭据、会话、源码片段、工具输出、产物和日志都可能包含隐私。检查后只分享必要片段。疑似安全漏洞请按 SECURITY.md 私下报告。