UnknownError通常源于ClawEngine未就绪、GPU驱动不兼容、模型文件异常或日志中的底层错误；需依次检查进程状态与端口、CUDA版本匹配性、模型路径完整性及日志堆栈。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试启动WorkBuddy并加载AI模型，但界面卡在“正在加载模型…”或控制台报出UnknownError，该错误通常指向底层推理引擎（如Triton、vLLM或自研ClawEngine）未就绪、崩溃或通信中断。以下是排查此问题的具体步骤：
一、验证ClawEngine进程是否存活并监听端口
WorkBuddy依赖本地运行的ClawEngine作为模型调度与执行核心，若该进程未启动、异常退出或端口被占用，将直接触发UnknownError。需确认其运行状态及网络可达性。
1、打开终端（Windows用户使用PowerShell或CMD，macOS/Linux用户使用Terminal）。
2、执行命令检查ClawEngine进程是否存在：
Windows：tasklist /fi "imagename eq ClawEngine.exe"
macOS/Linux：ps aux | grep ClawEngine
3、若未查到进程，进入WorkBuddy安装目录下的engine/子目录，手动运行ClawEngine --health-check，观察是否输出{"status":"ok","version":"v2.1.0"}。
4、若进程存在但无响应，执行端口连通性测试：curl -v http://127.0.0.1:8081/health（默认健康检查端口），预期返回HTTP 200及JSON格式健康状态；若返回connection refused或timeout，则引擎未监听或绑定失败。
二、检查GPU驱动与CUDA运行时兼容性
ClawEngine默认启用GPU加速推理，若CUDA驱动版本与引擎编译时依赖的CUDA Toolkit版本不匹配，会导致初始化失败并静默抛出UnknownError。需核对驱动版本与引擎要求的一致性。
1、在终端中运行nvidia-smi，记录顶部显示的CUDA Version（例如“CUDA Version: 12.4”）。
2、查阅WorkBuddy官方文档中当前版本（v2.3.1）所声明的ClawEngine CUDA支持矩阵，确认该版本明确支持CUDA 12.4而非仅支持至12.3。
3、若版本不匹配，前往NVIDIA官网下载对应版本的Driver Installer（非仅CUDA Toolkit），执行完整驱动重装，并重启系统。
4、重装后再次运行nvidia-smi，确认驱动版本与CUDA Version均更新到位，且clutch status（ClawEngine内置诊断命令）中cuda_available字段为true。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
三、校验模型权重文件完整性与路径映射
ClawEngine在启动时会预加载指定路径下的模型权重（如models/bailian-visual-zh-base/），若权重文件损坏、权限不足或路径配置指向空目录，引擎将无法完成初始化，最终以UnknownError对外暴露。
1、打开WorkBuddy设置界面，进入「高级」→「模型路径」，复制显示的模型根目录绝对路径。
2、在终端中切换至该路径，执行ls -la models/bailian-visual-zh-base/，确认存在config.json、pytorch_model.bin（或model.safetensors）及tokenizer*.*等关键文件。
3、检查文件权限：ls -ld models/bailian-visual-zh-base/，确保当前用户对该目录具有读取与执行权限（即r-x或rwx）；若为drwx------且属主非当前用户，需执行sudo chown -R $USER:$USER models/bailian-visual-zh-base/。
4、手动触发权重校验：ClawEngine --validate-model models/bailian-visual-zh-base/，等待输出✓ Model signature verified。
四、查看ClawEngine日志中的原始错误堆栈
UnknownError是前端封装后的通用错误码，真实原因隐藏在ClawEngine后台日志中。直接读取日志可定位到具体模块（如TensorRT初始化失败、共享内存段创建拒绝等）。
1、定位日志目录：
Windows：%APPDATA%\Tencent\WorkBuddy\logs\clawengine\
macOS：~/Library/Logs/WorkBuddy/clawengine/
Linux：~/.local/share/WorkBuddy/logs/clawengine/
2、按修改时间排序，打开最新生成的engine-*.log文件，搜索关键词FATAL、ERROR或Failed to initialize。
3、若发现类似Failed to create shared memory segment: Permission denied，说明系统shm限制过低，需执行：
Linux：sudo sysctl -w kernel.shmmax=2147483648
macOS：sudo sysctl -w kern.sysv.shmmax=2147483648
4、保存日志片段，重点截取从“Starting ClawEngine”到首次出现ERROR之间的连续20行，用于后续技术支援提交。
